WBTC MCP Server

WBTC MCP Server lets MCP-compatible AI clients read public WBTC transparency data directly. You can connect it to Claude Desktop, Claude Code, Cursor, Codex CLI, and other MCP hosts, then ask natural-language questions about WBTC reserve ratio, circulating supply, BTC reserves, supported chains, mint/burn records, custodians, merchants, and ecosystem projects.

The server runs locally over stdio and reads data from the WBTC Public API. It is read-only: it does not connect to wallets, hold private keys, sign transactions, or broadcast transactions.

What You Can Query

Capability	Tool	Description
Reserve ratio	`get_proof_of_reserve`	Query current WBTC collateralization health and return `reserveRatio`.
Supply	`get_supply`	Query current WBTC circulating supply and Native-chain supply distribution.
Reserves	`get_reserves`	Query BTC reserve amount, BTC price, and reserve value in USD.
Reserve addresses	`list_custodian_addresses`	Query public BTC reserve addresses, balances, and explorer URLs.
Supported chains	`list_chains`	Query Native / Bridge chains with public contract addresses and explorer URLs.
Mint / Burn	`list_mint_burn_records`	Query public WBTC mint/burn records with pagination.
Merchants	`list_merchants`	Query the public WBTC merchant directory.
Custodians	`list_custodians`	Query the public WBTC custodian directory.
Ecosystem	`list_ecosystem_projects`	Query public WBTC ecosystem projects.

Installation

Make sure Node.js 20 or later is installed.


npm install -g @wbtc-mcp/wbtc-mcp

After installation, the global command is:


wbtc-mcp

If you prefer not to install globally, you can run the server from your MCP client with npx:


npx -y @wbtc-mcp/wbtc-mcp

Configure Your MCP Client

Claude Desktop

Add the following configuration to Claude Desktop.

On macOS, the config file is usually located at:


~/Library/Application Support/Claude/claude_desktop_config.json

Configuration example:


{
  "mcpServers": {
    "wbtc": {
      "type": "stdio",
      "command": "wbtc-mcp",
      "env": {
        "WBTC_PUBLIC_API_TIMEOUT_MS": "15000"
      }
    }
  }
}

If you use npx:


{
  "mcpServers": {
    "wbtc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wbtc-mcp/wbtc-mcp"],
      "env": {
        "WBTC_PUBLIC_API_TIMEOUT_MS": "15000"
      }
    }
  }
}

Claude Code

Create or update .mcp.json in your project root:


{
  "mcpServers": {
    "wbtc": {
      "type": "stdio",
      "command": "wbtc-mcp",
      "env": {
        "WBTC_PUBLIC_API_TIMEOUT_MS": "15000"
      }
    }
  }
}

Cursor

Add this to .cursor/mcp.json:


{
  "mcpServers": {
    "wbtc": {
      "type": "stdio",
      "command": "wbtc-mcp",
      "env": {
        "WBTC_PUBLIC_API_TIMEOUT_MS": "15000"
      }
    }
  }
}

Codex CLI

Add this to ~/.codex/config.toml:


[mcp_servers.wbtc]
command = "wbtc-mcp"
startup_timeout_sec = 30
default_tools_approval_mode = "approve"
 
[mcp_servers.wbtc.env]
WBTC_PUBLIC_API_TIMEOUT_MS = "15000"

Configuration

Environment variable	Default	Description
`WBTC_PUBLIC_API_TIMEOUT_MS`	`8000`	Timeout for WBTC Public API requests, in milliseconds.

The WBTC Public API base URL is fixed:


https://openapi.wbtc.network/public/v1

You do not need to configure WBTC_PUBLIC_API_BASE_URL. The server does not read wallet keys, seed phrases, cloud credentials, or signing configuration.

Example Prompts

After connecting the MCP server, you can ask:


What is WBTC's current reserve ratio?


What is WBTC's current circulating supply? Break it down by Native chain.


How much BTC reserve does WBTC have, and what is the USD value?


List WBTC supported native chains and contract addresses.


Show the latest 20 WBTC mint/burn records.


Who are the WBTC custodians?


Which DeFi projects are in the WBTC ecosystem?

If your client has multiple tools enabled, you can be explicit:


Use the WBTC MCP tools to answer.

Tool Reference

`get_proof_of_reserve`

Query the current WBTC reserve ratio.

No input parameters.

Main returned fields:

Field	Description
`reserveRatio`	Reserve ratio as a decimal string. `1.0` means fully backed.
`meta.updatedAt`	Data update timestamp.

`get_supply`

Query current WBTC circulating supply and Native-chain supply distribution.

No input parameters.

Main returned fields:

Field	Description
`circulatingSupply`	WBTC circulating supply as a decimal string.
`byChain[]`	Native-chain supply records.
`byChain[].chain`	Chain name.
`byChain[].chainKey`	Chain identifier.
`byChain[].supply`	WBTC supply on this chain.

`get_reserves`

Query WBTC reserve asset summary.

No input parameters.

Main returned fields:

Field	Description
`nativeBtcReserve`	BTC reserve amount as a decimal string.
`btcPriceUsd`	BTC price in USD as a decimal string.
`reserveValueUsd`	Reserve value in USD as a decimal string.

`list_custodian_addresses`

Query public BTC reserve address evidence.

No input parameters.

Main returned fields:

Field	Description
`addresses[]`	Reserve address list.
`addresses[].address`	BTC address.
`addresses[].balanceBtc`	Address balance in BTC.
`addresses[].explorerUrl`	Blockchain explorer URL.
`total`	Number of addresses.

`list_chains`

Query supported WBTC chains and public contract metadata.

Optional input parameters:

Parameter	Description
`type`	Optional value: `native` or `bridge`. If omitted, all chain types are returned.

Main returned fields:

Field	Description
`natives[]`	Native chain list.
`bridges[]`	Bridge chain list.
`chain`	Chain name.
`chainKey`	Chain identifier.
`isNew`	Whether the chain is newly supported.
`contract.contractType`	Contract standard.
`contract.contractAddress`	WBTC contract address.
`contract.explorerUrl`	Blockchain explorer URL.

`list_mint_burn_records`

Query public WBTC mint/burn records with pagination.

Optional input parameters:

Parameter	Description
`pageIndex`	Page index, starting from 1.
`pageSize`	Number of records per page. Values above 200 are capped by the Public API.
`action`	Mint/burn action filter.
`status`	Status filter.
`network`	Network filter.
`merchantName`	Merchant name filter.

Main returned fields:

Field	Description
`records[]`	Mint/burn record list.
`records[].action`	Mint or burn.
`records[].status`	Record status.
`records[].network`	Network.
`records[].amount`	Amount in WBTC.
`records[].merchantName`	Merchant name.
`records[].date`	Record timestamp.
`records[].txHash`	Transaction hash.
`meta.pagination`	Pagination information.

`list_merchants`

Query the public WBTC merchant directory.

Optional input parameters:

Parameter	Description
`tag`	Filter by public tag.

Main returned fields:

Field	Description
`merchants[]`	Merchant list.
`name`	Name.
`description`	Description.
`tags[]`	Public tags.
`website`	Website URL.

`list_custodians`

Query the public WBTC custodian directory.

No input parameters.

Main returned fields:

Field	Description
`custodians[]`	Custodian list.
`name`	Name.
`description`	Description.
`website`	Website URL.

`list_ecosystem_projects`

Query public WBTC ecosystem projects.

Optional input parameters:

Parameter	Description
`category`	Optional value: `defi`, `chains`, `wallet`, or `bridge`.
`network`	Filter by network tag.

Main returned fields:

Field	Description
`projects[]`	Ecosystem project list.
`name`	Project name.
`category`	Category.
`networks[]`	Network tags.
`url`	Project URL.

Response Format

Each tool returns an MCP CallToolResult. On success, the main data is in structuredContent.data, and metadata is in structuredContent.meta.

Success example:


{
  "content": [
    {
      "type": "text",
      "text": "WBTC reserve ratio is 1.00006452. Updated at 2026-06-26T00:00:00Z."
    }
  ],
  "structuredContent": {
    "data": {
      "reserveRatio": "1.00006452"
    },
    "meta": {
      "updatedAt": "2026-06-26T00:00:00Z",
      "version": "v1",
      "source": "wbtc.network/transparency"
    }
  },
  "isError": false
}

Error example:


{
  "content": [
    {
      "type": "text",
      "text": "WBTC public data is temporarily unavailable. Please retry later; do not interpret this as reserves being zero."
    }
  ],
  "structuredContent": {
    "error": {
      "code": "UPSTREAM_UNAVAILABLE",
      "message": "WBTC public data is temporarily unavailable. Please retry later; do not interpret this as reserves being zero.",
      "hint": "Retry later and report the Public API availability issue if it persists. Do not treat missing data as zero.",
      "retryable": true,
      "details": {
        "httpStatus": 503
      }
    }
  },
  "isError": true
}

Error codes:

Code	Meaning	Recommended retry
`INVALID_PARAM`	Parameters do not match the tool schema.	No
`RATE_LIMITED`	Public API is rate limited or temporarily overloaded.	Yes
`UPSTREAM_UNAVAILABLE`	Public API is temporarily unavailable, network failed, or request timed out.	Yes
`UPSTREAM_CONTRACT_ERROR`	Public API response does not match the expected contract.	No
`INTERNAL_ERROR`	Unexpected MCP server error.	No

If the server returns UPSTREAM_UNAVAILABLE, do not interpret it as zero WBTC reserves or zero supply.

Security

WBTC MCP Server is read-only:

It does not connect to wallets.
It does not request private keys, seed phrases, or signing permissions.
It does not send transactions.
It does not accept user-provided URLs.
It does not forward user tokens, cookies, or API keys.
It only accesses the public WBTC Public API.

All business data comes from public endpoints. AI clients should present the returned data together with the update timestamp.

FAQ

I cannot see the WBTC tools in my client

Check the following:

Node.js 20 or later is installed.
The wbtc-mcp command is available in your terminal.
The MCP client configuration file has been saved and the client has been restarted.
If you use npx, make sure your network can access the npm registry.

Calls fail or time out

Confirm that your machine can access:


https://openapi.wbtc.network/public/v1

If the network is slow, increase WBTC_PUBLIC_API_TIMEOUT_MS, for example to 15000 or 30000.

Do I need an API key?

No. WBTC MCP Server reads public WBTC transparency data only.

Can I change the API base URL?

No. The server always uses:


https://openapi.wbtc.network/public/v1

Does it support write operations?

No. WBTC MCP Server only provides read-only queries. It does not support mint, burn, transfer, approve, sign, broadcast, or other write operations.