name: trezor-mcp description: Trigger on any mention of Trezor wallet interaction, crypto addresses, sending crypto, checking balances, signing messages, or hardware wallet operations via MCP. Also trigger when users mention configuring or troubleshooting the Trezor MCP server connection.

Trezor Suite MCP Server

The Trezor Suite MCP server lets AI agents interact with Trezor hardware wallets over the Model Context Protocol. It runs locally inside Trezor Suite Desktop and exposes tools for getting addresses, checking balances, sending transactions, and signing/verifying messages. All sensitive operations require physical confirmation on the Trezor device.

Setup & Configuration

Prerequisites

1. Trezor Suite Desktop installed and running
2. Trezor device connected via USB
3. MCP server enabled: Settings → Experimental Features → enable experimental features → check MCP Server

Once enabled, the server listens at http://127.0.0.1:21340/mcp (localhost only).

Client Configuration

Replace <token> with the token shown in the Trezor Suite config snippet (Settings → Experimental Features → MCP Server). The token is passed as a URL query parameter — no custom headers needed.

Claude Code — run in your terminal:

claude mcp add trezor-suite http://127.0.0.1:21340/mcp?token=<token> -t http

This adds the server to the current project (local scope). To make it available in all projects, add -s user. If you see "SDK auth failed", see the troubleshooting section below for the mcp-remote workaround.

Claude Desktop — add this to claude_desktop_config.json (requires Node.js for npx):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "trezor-suite": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://127.0.0.1:21340/mcp?token=<token>",
                "--transport",
                "http-only",
                "--allow-http"
            ]
        }
    }
}

Claude Desktop only supports stdio transport, so mcp-remote acts as a bridge: it spawns a local process that translates between stdio and the Trezor Suite HTTP server. The --allow-http flag is required because the server runs on localhost over HTTP (not HTTPS). The --transport http-only flag skips SSE transport attempts.

Other MCP clients — add this JSON to your client config:

{
    "mcpServers": {
        "trezor-suite": {
            "url": "http://127.0.0.1:21340/mcp?token=<token>"
        }
    }
}

Verifying the Connection

• Claude Code: run /mcp to see connected servers
• Manual test: curl -X POST http://127.0.0.1:21340/mcp -H "Content-Type: application/json" -H "Authorization: Bearer <token>" -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

A successful response returns protocolVersion and serverInfo.

Available Tools — Quick Reference

Common Workflows

Get a Receive Address

Use trezor_get_address with the coin and derivation path.

Bitcoin (native segwit):

{ "coin": "btc", "path": "m/84'/0'/0'/0/0", "showOnTrezor": true }

Ethereum:

{ "coin": "eth", "path": "m/44'/60'/0'/0/0", "showOnTrezor": true }

Set showOnTrezor: true when the user wants to verify the address on their device screen. For programmatic lookups where verification is not needed, omit it or set it to false.

Check Account Balance

Use trezor_get_account_info with the coin and an account-level path.

Bitcoin:

{ "coin": "btc", "path": "m/84'/0'/0'", "details": "basic" }

Ethereum:

{ "coin": "eth", "path": "m/44'/60'/0'/0/0", "details": "tokenBalances" }

The response includes balance (in the smallest unit — satoshis for BTC, wei for ETH), availableBalance, and transaction history depending on the details level:

• "basic" — balance only
• "tokens" / "tokenBalances" — include token info (useful for EVM)
• "txids" / "txs" — include transaction IDs or full transaction objects

Send a Transaction

Use trezor_send_transaction. For simple transfers you only need coin, to, and value — nonce, fees, and UTXOs are auto-filled.

Send 0.001 BTC:

{ "coin": "btc", "to": "bc1q...", "value": "0.001" }

For UTXO coins, the tool auto-handles account discovery, UTXO selection, fee estimation, signing, and broadcasting in one call.

Send 0.1 ETH:

{ "coin": "eth", "to": "0xABC...123", "value": "0.1" }

EVM auto-fill: nonce from account state, fees estimated via EIP-1559 (falls back to legacy if gasPrice is explicitly provided).

Send 10 XRP:

{ "coin": "xrp", "to": "rN7d...", "value": "10", "destinationTag": 12345 }

XRP auto-fill: sequence number and fee (defaults to 12 drops if estimation fails).

Important: The user confirms the transaction details physically on their Trezor device — do not ask for separate confirmation in chat. Just call the tool directly and let the device handle approval.

Common Stablecoin Contracts

When the user asks to send stablecoins, always ask which stablecoin and which network before proceeding — never assume.

IMPORTANT: Never show the user any of the following — contract addresses, hex data, calldata encoding, function selectors, decimal conversions, or any implementation details. The user should only see: "Sending X USDT to [address] on Ethereum. Please confirm on your Trezor device." Nothing more.

Call trezor_send_transaction with tokenContract and tokenDecimals — the server encodes the ERC-20 transfer calldata automatically. No hex encoding needed.

• coin: the network — "eth" for Ethereum, "base" for Base
• to: the recipient address
• value: token amount in human units (e.g. "10" for 10 USDC)
• tokenContract: the token's contract address
• tokenDecimals: the token's decimal places

Example — send 10 USDC on Ethereum:

{
    "coin": "eth",
    "to": "0xRecipientAddress",
    "value": "10",
    "tokenContract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenDecimals": 6
}

The server handles calldata encoding, nonce, EIP-1559 fees, gas limit, signing, and broadcasting.

Ethereum (eth) contracts:

• USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (6 decimals)
• USDT: 0xdAC17F958D2ee523a2206206994597C13D831ec7 (6 decimals)
• DAI: 0x6B175474E89094C44Da98b954EedeAC495271d0F (18 decimals)

Base (base) contracts:

• USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (6 decimals)
• DAI: 0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb (18 decimals)

To send from a non-default account, use accountIndex (0-based) or provide an explicit path.

If you need to sign without broadcasting, set "broadcast": false. The response will contain the signed transaction hex, which you can later broadcast with trezor_push_transaction.

Sign & Verify a Message

Sign:

{ "coin": "btc", "path": "m/84'/0'/0'/0/0", "message": "Hello, world!" }

Returns { "address": "bc1q...", "signature": "base64..." }.

Verify:

{ "coin": "btc", "address": "bc1q...", "message": "Hello, world!", "signature": "base64..." }

Returns a success/failure result.

Sign EIP-712 Typed Data

Use trezor_sign_typed_data to sign EIP-712 structured data on EVM chains. Common use cases include token permits (EIP-2612), NFT marketplace orders, and DAO governance votes.

EIP-2612 permit example (approve USDC spending without a transaction):

{
    "data": {
        "types": {
            "EIP712Domain": [
                { "name": "name", "type": "string" },
                { "name": "version", "type": "string" },
                { "name": "chainId", "type": "uint256" },
                { "name": "verifyingContract", "type": "address" }
            ],
            "Permit": [
                { "name": "owner", "type": "address" },
                { "name": "spender", "type": "address" },
                { "name": "value", "type": "uint256" },
                { "name": "nonce", "type": "uint256" },
                { "name": "deadline", "type": "uint256" }
            ]
        },
        "primaryType": "Permit",
        "domain": {
            "name": "USD Coin",
            "version": "2",
            "chainId": 1,
            "verifyingContract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        },
        "message": {
            "owner": "0xYourAddress",
            "spender": "0xSpenderContract",
            "value": "1000000",
            "nonce": "0",
            "deadline": "1735689600"
        }
    }
}

The path is auto-derived for Ethereum (account index 0) if omitted. Use accountIndex to select a different account, or provide an explicit path.

Broadcast a Pre-Signed Transaction

Use trezor_push_transaction when you have a signed transaction hex (e.g., from a send_transaction call with broadcast: false):

{ "coin": "eth", "tx": "0xf86c..." }

Coin & Path Conventions

Common coins and their default derivation paths:

For the full list of supported coins (including testnets, EVM L2s, and decimals), see references/tools-reference.md.

Safety & Confirmation Model

• All signing and sending operations require physical confirmation on the Trezor device. This is the primary safety gate — no transaction can be signed without the user pressing a button on their hardware wallet.
• Read-only tools (get_account_info, get_address without showOnTrezor, verify_message) do not require device interaction.
• Do not ask for confirmation in chat before calling tools. The Trezor device is the confirmation mechanism — the user reviews and approves every transaction on the device screen. Asking in chat is redundant and slows down the workflow. Just call the tool directly.
• The MCP server only accepts connections from localhost — it cannot be accessed remotely.
• Bearer token authentication is required on every request. The token is auto-generated when MCP is first enabled and included in the config snippet. Requests without a valid Authorization: Bearer <token> header receive HTTP 401.

Agent Recovery: MCP Tools Not Available

If the Trezor MCP tools are not showing up as connected tools, follow these steps in order — do NOT fall back to raw HTTP/curl:

1. Retry the MCP connection. In Claude Code, run /mcp to reconnect. The server may have just started.
2. If still not connected, tell the user the auth token is likely missing or wrong. Say: "The Trezor MCP server isn't connected. Please check that the Bearer token in your MCP client config matches the one shown in Trezor Suite → Settings → Experimental Features → MCP Server. Copy the full config snippet and paste it into ~/.claude.json (or your MCP client config), then restart the MCP connection."
3. If the user confirms the token is correct, check the basics: Is Trezor Suite running? Is the MCP server toggle enabled in Settings → Experimental Features?
4. Never bypass the MCP protocol by sending raw HTTP requests to the server. Always use the MCP tools through the proper MCP client connection.

Troubleshooting

References

For detailed tool parameters, all supported coins with paths and decimals, example JSON-RPC payloads, transaction auto-fill details, and error codes, read references/tools-reference.md.