Docs
MCP server
Ask your AI assistant about gold, silver, platinum, palladium and copper prices, derived metrics, country monetary data and your own portfolio. The Bullion API MCP server is read-only: it can look things up and can never change anything.
Connect
The server is at https://api.bullionapi.dev/mcp and speaks Streamable HTTP with OAuth 2.1. Add that address to any agent that supports remote MCP servers with sign-in, such as Claude, ChatGPT, Cursor, VS Code or Gemini CLI. The agent registers itself the first time it connects; you then sign in with your Bullion API account and approve exactly what it may read.
The approval page shows the agent's name as unverified, because any agent can choose its name. Check where you will be sent next and approve only a connection you started.
You can connect directly without a directory listing. Client availability depends on your plan and workspace permissions. The instructions below do not imply that Bullion API has been approved or listed in any client directory.
Cursor
Open this link on a computer with Cursor installed. Review the server URL in Cursor, confirm installation, then complete Bullion API sign-in and approve the read permissions. The button opens Cursor; it does not grant access by itself.
Manual setup
If the link does not open, add this configuration to ~/.cursor/mcp.json for personal use, or .cursor/mcp.json in your project. Merge it with any existing servers. Open Cursor's MCP settings and connect Bullion API.
{
"mcpServers": {
"bullion-api": {
"url": "https://api.bullionapi.dev/mcp"
}
}
}ChatGPT
- Open ChatGPT Plugins, select the plus button, then Add custom MCP server.
- Name it Bullion API and enter
https://api.bullionapi.dev/mcpas the server URL. - Choose OAuth authentication. Use automatic client registration if prompted; do not enter an API key.
- Review ChatGPT's connection warning, create the plugin, then sign in to Bullion API and approve the requested read access.
- Enable the connection in your chat and ask:
Get the latest available gold price in USD, with its observation date.
If custom MCP setup is unavailable, check your workspace's plugin permissions with its administrator. Menu labels and availability can vary. Follow the current ChatGPT setup guide.
Claude
- Open Settings → Connectors and choose Add custom connector.
- Enter Bullion API and
https://api.bullionapi.dev/mcp. - Review the detected OAuth settings, connect, then sign in to Bullion API and approve read access.
- Enable the connector for your conversation and ask for a dated gold observation.
Claude connector guide. Your workspace may require administrator approval.
Claude Code
claude mcp add --transport http bullion https://api.bullionapi.dev/mcpThen run /mcp, choose bullion and sign in. Approve Stay connected to stay connected without signing in again every few minutes.
Grok
- Open Grok Connectors and choose New Connector → Custom.
- Enter
https://api.bullionapi.dev/mcpand complete the OAuth sign-in flow. - Approve Bullion API read access and ask Grok for a dated gold observation.
Business and Enterprise teams may need their administrator to provision the connector. See the Grok connector guide.
Muse
Bullion API's Muse connector is not available through a confirmed directory listing yet. Once approved and published, find Bullion API in Settings → Connectors, connect your account and approve read access. We will add the installation link here when it is available.
These instructions refer to Meta's Muse. Its connector guidelines describe approval and discovery; they do not establish a public custom-URL installation flow.
Check your connection
After sign-in, ask for the supported symbols, then a gold observation with its date and freshness. If data is unavailable or your plan limit is reached, the agent should explain the result without inventing a value. Connecting and listing tools are free; data calls use your account's credits and limits.
If sign-in fails, confirm the exact server URL, your client's remote MCP and OAuth support, and workspace permissions. Reconnect through the client if consent expires or is withdrawn. Never paste credentials into a chat or configuration example. Approve Stay connected only if you want the client to renew access automatically. Contact support if it still fails.
What you approve
| Permission | What it allows |
|---|---|
Market datamarket:read | Read precious-metals market prices and related market data. |
Macroeconomic datamacro:read | Read macroeconomic indicators and time series. |
Your private portfolioportfolio:read | Read your account’s private portfolio and transaction history. This does not allow changes. |
Stay connectedoffline_access | Keep this connection working for up to 30 days without signing in again. Access to your data is still renewed every five minutes. |
Access tokens last five minutes and are renewed automatically while the connection is active. Withdrawing your approval ends the connection immediately.
Tools
| Tool | Description | Permission |
|---|---|---|
get_metal_price | Latest cached spot price for one metal, in a currency and weight unit (default USD per troy ounce). One dated observation; cached, not real-time. | market:read |
get_metal_price_history | Cached weekday closing prices for one metal as a dated time series. start is required; end defaults to today. Suited to a table or line chart. | market:read |
get_metal_change | Price change for one metal over a period (1d, 1w, 1m, 1y) or between a start and end date: start and end prices, the change, and change_percent relative to the start price. | market:read |
get_gold_carat | Gold price per gram for each karat (24k down to 6k) in a currency, for the latest cached day or a given date. | market:read |
get_gold_silver_ratio | Gold-to-silver price ratio as a dated series. Give start and end together for a range, or neither for the latest value. | market:read |
get_gold_moving_average | Simple moving average of gold closes (50 or 200 closes), per troy ounce, as a dated series. start, end and window are required. | market:read |
get_gold_volatility | Annualised volatility of 30 daily gold returns as a dated series of fractions (0.15 means 15%). start and end are required. | market:read |
get_gold_drawdown | Gold drawdown from its running peak as a dated series of fractions at or below zero (-0.25 means 25% below the peak). start and end are required. | market:read |
get_gold_real_price | USD gold rebased with official seasonally adjusted CPI-U index levels to the latest stored published reference month. start/end required; missing months omitted and absent source returns dependency_not_ready. Eight-place decimal strings, not point-in-time vintages. | market:read |
get_gold_yield_correlation | 90-pair rolling Pearson correlation of daily USD gold simple returns and daily 10-year real Treasury yield changes. Current and previous dates must match; incomplete/zero-variance windows omitted. start/end required; stored inputs only. | market:read |
get_central_bank_reserves | Central-bank reserves. Omit country for the latest value of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_central_bank_gold | Central-bank gold holdings. Omit country for a compact summary of the latest holdings and value of every covered country; give a country (and optional start and end) for its history, stock changes and methodology. | macro:read |
get_inflation | Inflation by country and basis (year_over_year, breakeven, implied, expectation). Omit country for the latest value of every covered country. | macro:read |
get_policy_rates | Central-bank policy rates. Omit country for the latest rate of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_bond_yields | Government bond yields by tenor (2y, 5y, 10y, 30y) and basis. Omit country for the latest yields of every covered country. | macro:read |
get_dollar_index | Federal Reserve Board nominal broad trade-weighted U.S. dollar index (January 2006 = 100), one value per business day; higher means a stronger dollar. Omit start and end for the latest day; give start (and optional end) for history, at most 10 years. | macro:read |
get_money_supply | Money supply by country. Omit country for the latest value of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_central_bank_balance_sheet | Central-bank balance-sheet series. Omit country for the latest value of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_government_debt | Government debt. Omit country for the latest value of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_government_borrowing | Government borrowing. Omit country for the latest value of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_debt_interest | Government debt interest costs. Omit country for the latest value of every covered country; give a country (and optional start and end) for its history. | macro:read |
get_government_debt_holders | Who holds government debt held by the public: foreign and international investors, the central bank, and everyone else (a calculated difference). United States only, quarterly. Omit country for the latest values; give a country (and optional start and end) for its history. | macro:read |
get_market_indicators | Annual U.S. Geological Survey (USGS) gold or silver statistics in metric tonnes: world and US mine production, US recycling, US silver consumption, and US imports and exports (no gold consumption). Omit start and end for the latest year; USGS lags several years. Partial indicators, not total demand or a market balance. Credit the U.S. Geological Survey, which does not endorse this service. | market:read |
get_us_treasury_holdings | Monthly foreign holdings of U.S. Treasury securities at market value, in millions of USD, with the change from the previous month. Omit holder for the latest month: the total, the official/non-official split and every country, largest first. Give holder (a country code, or total, official or non-official) and optional start and end for its history. Holdings are attributed to where the custodian is based, not the beneficial owner, so custody centres such as Belgium, Luxembourg, the UK and the Cayman Islands hold for investors elsewhere. Published about six weeks after each month ends. | macro:read |
list_countries | Countries that have per-country datasets, with which datasets each has. Use it to discover where data exists before querying. | macro:read |
get_country | Which datasets exist for one country or aggregate code such as EA (euro area). | macro:read |
list_symbols | The metals and currencies this service supports, in the configured serviceable catalogue. | market:read |
get_portfolio | Summary of the connected account's portfolio: holdings in grams, cost basis, realised and unrealised profit and loss, valued at the latest cached spot price. Takes no account id; it always reads the connected account. | portfolio:read |
get_portfolio_lots | Open lots (purchases not yet sold) with remaining quantity and cost, for the connected account only. | portfolio:read |
get_portfolio_gains | Realised gains and losses for one calendar year or one UK tax year, grouped by capital-gains status, for the connected account only. Give exactly one of calendar_year or uk_tax_year. | portfolio:read |
list_portfolio_transactions | The connected account's purchases and sales, paged with limit and cursor (next_cursor is null on the last page). Filter by type, form, capital-gains status or one year. | portfolio:read |
get_portfolio_transaction | One transaction by id for the connected account only, with its lots and allocations. Use an id from list_portfolio_transactions. | portfolio:read |
Ready-made prompts
- Gold overview (
gold_overview): Latest gold price with recent change, volatility and drawdown. - Compare precious metals (
compare_metals): Gold, silver, platinum and palladium side by side, with the gold-silver ratio. - Country macro snapshot (
macro_snapshot): Inflation, policy rate, bond yields, money supply and government debt for one country. - Portfolio review (
portfolio_review): My holdings, current value, gains and recent transactions.
Example
get_metal_price_history {"metal":"gold","start":"2026-09-28","end":"2026-10-05"}**Get metal price history**: gold, USD, 2026-09-28 to 2026-10-05.
Gold spot price (daily, weekday_close, per troy_oz)
| Date | Value |
|------------|---------------|
| 2026-09-28 | 3499.67053894 |
| 2026-09-29 | 3499.50566282 |
| ... | ... |
Cached observations, not real-time quotes.Every result also carries the exact data as structured JSON. Prices and quantities are decimal strings, never rounded floats.
Credits, privacy and limits
- Market and macro calls use the same credits and plan limits as the REST API. Connecting, signing in and listing tools are free.
- Portfolio tools read only the account that signed in, and never another account.
- Each connection is limited to 60 requests a minute.
- Data is cached, not real-time. Prices are informational only and are not financial advice.
- When no data is stored for a request, the tool returns
no_datarather than an estimate.