Install and configure the IronWallet MCP server for Cursor, Claude Code, ChatGPT, and other MCP clients.
The IronWallet MCP server (@ironwallet/mcp-server) gives AI agents a non-custodial crypto wallet on your computer. Seed phrases are generated and encrypted locally — they never leave this machine and never pass through the agent, the LLM, or IronWallet backends. Agents can check balances, show deposit QR codes, transfer tokens, and swap across 12 networks: Ethereum, BSC, Polygon, Base, Arbitrum, Optimism, Avalanche, Tron, Bitcoin, Solana, XRP, and TON.
There is no per-transaction confirmation UI — once you ask the agent to send or swap, it can sign and broadcast without asking again. Use a dedicated hot wallet with a limited balance, never your main wallet.
Requirements: Node.js 20+ (npx). Desktop / stdio only.
Non-custodial, local signing
Seed phrases stay encrypted on the host (owner-only file permissions). Transactions are signed on this machine; no tool accepts or returns a seed.
Wallets in the local browser
Create wallets with create_wallets (returns a backup_url), or import and back up through open_wallet_manager — a loopback-only page on 127.0.0.1 that shuts down after 15 minutes of inactivity. Secrets appear only in that browser page, never in chat.
Transfers with fee estimates
estimate_transfer previews the fee without broadcasting; send_transfer signs locally and sends; get_operation_status polls the result. The server may reduce the amount slightly so the fee still fits the balance — the response says when that happened.
Catalog-driven swaps
list_swap_networks and list_swap_assets provide the sell/buy catalog so the agent never invents token addresses. estimate_swap quotes, execute_swap executes on a fresh quote, get_swap_status polls.
Deposit QR codes
get_deposit_qr returns a PNG for chat plus a local qr_url fallback.
Optional spending limits
Per-wallet policy via set_wallet_policy: readOnly, maxPerTxUsd, and a transfer recipient allow-list. Off by default; applies to both sends and swaps. IW_READ_ONLY=true makes the whole server read-only.
Tronscannerpolicybackup_urlreadOnly, maxPerTxUsd, allow-list)qr_url)No tool accepts or returns a seed. Import, backup, and delete only in the local browser (open_wallet_manager / backup_url); deleting asks the user to retype the wallet name.
Typical flows:
Transfer: list_wallets / get_balance → estimate_transfer (optional) → send_transfer → get_operation_status if you need to wait.
Swap: list_swap_networks → list_swap_assets → estimate_swap or execute_swap → get_swap_status. Token addresses and decimals come from the catalog, never from model memory.
Option 1: npx (recommended)
Use npx to run the server without global installation. This ensures you always use the latest version.
First launch can take ~30 seconds while dependencies install. If your MCP client times out, run the command once in a terminal to warm the cache, then reconnect.
Option 2: Global install
Install the package globally for faster startup, then run ironwallet-mcp.
Each client has a dedicated static URL (for example /ai/introduction/vscode/). All install commands below are also inlined on this page — no tabs, nothing hidden behind clicks.
Most recommended
Works well with free version, easy install, best experience
Install once. After that, the wallet tools are available in every chat. You can also paste this into ~/.cursor/mcp.json and restart Cursor.
Reload Cursor after install so PATH includes npx.
Standalone page for Cursor — one HTTP fetch returns only this guide.
Requires higher expert level
Works well with Code mode, Chat mode is very limited
Run these commands in order:
After plugin install, wait ~45 seconds and start a new chat so the tools load.
Or point Claude Code at the stdio server directly:
Standalone page for Claude Code — one HTTP fetch returns only this guide.
Highest expert level
Requires additional plugins with paid version of AI models
Opens VS Code and registers the local MCP server. You can also add this to your VS Code MCP settings (user or workspace).
Standalone page for VS Code — one HTTP fetch returns only this guide.
Easy setup - requires Codex
Free version is very limited, paid version works better
Run these commands in order, then reload so the MCP tools are available.
Or point ChatGPT at the stdio server directly:
Standalone page for ChatGPT — one HTTP fetch returns only this guide.
Use the stdio transport. Point your MCP client to:
Standalone page for Other clients — one HTTP fetch returns only this guide.
There is no sign-in and no account. On first launch the server generates its local secrets — a relay API key, a keystore wrapping secret, and a device id — under ~/.ironwallet-mcp/ with owner-only permissions. Nothing to configure.
To start using a wallet:
accept_mcp_consent), or you press Continue in the wallet manager.create_wallets returns wallet names and addresses plus a backup_url — open it in your browser to view and back up the recovery phrase. To import an existing wallet or make a backup later, use open_wallet_manager. The recovery phrase is typed or shown only in the local browser page, never in chat.get_deposit_qr) or an address (list_wallets) and send a small amount. Keep the balance limited — this is a hot wallet.The server keeps its state in ~/.ironwallet-mcp/ (override with IW_KEYSTORE_DIR):
the encrypted keystore with your wallet seeds,
the wrapping secret, relay API key, and device id,
diagnostic logs under logs/ (seed material is never logged).
Warning: do not delete this directory to “reset” the server.
It contains the encrypted keys to your funds. If you remove it without having backed up the recovery phrase in the wallet manager, the funds are lost. Your backup is the recovery phrase, not these files.
Anyone with the keystore and the wrapping secret controls the funds, so treat the directory as sensitive.
Most users do not need to set any environment variables. The server generates and stores everything it needs on first launch. The following are available for advanced use:
send_transfer and execute_swap process-wide. Distinct from per-wallet policy.readOnly0 to disable)debug / info / warn / errorSeeds never leave this machine. They are encrypted at rest and never appear in tool results, agent chat, logs, or backend requests. No tool accepts or returns a seed — import and backup happen only in the local browser.
The agent can move funds without asking again. There is no per-transaction confirmation UI; your chat message is the authorization. Transfers and swaps are irreversible once broadcast.
Optional limits. Per-wallet policy (readOnly, maxPerTxUsd, recipient allow-list) via set_wallet_policy, and server-wide IW_READ_ONLY=true. Both are off by default.
Hot wallet only. Do not import your main or savings wallet. Anyone with the keystore and the wrapping secret controls the funds; a leaked seed cannot be revoked.
Timeout is not failure. Poll get_operation_status / get_swap_status before retrying a send or swap.
All backend requests use HTTPS; local secret files use owner-only permissions (Unix 0600, NTFS ACL on Windows).
Vulnerability disclosure: SECURITY.md.
Test the server directly using the MCP inspector. This opens an interactive web UI where you can test tool calls without an AI assistant.
npx downloads the package on first run, which can take ~30 seconds.
npx -y @ironwallet/mcp-server once in a terminal to warm the cache, then reconnect.npm install -g @ironwallet/mcp-server@latest.node --version.PATH includes npx.create_wallets returns needs_consentThe MCP disclaimer has not been accepted yet. Ask the agent to show the full disclaimer and confirm (accept_mcp_consent), or open the wallet manager and press Continue.
A timeout is not a failure — the transaction may already be broadcast. Poll get_operation_status (transfers) or get_swap_status (swaps) before retrying. Never resubmit blindly.
list_wallets → policy: readOnly or a recipient allow-list may be blocking the operation. { enabled: false } means no limits.maxPerTxUsd fails closed: if no USD rate is available for the asset, the operation is rejected.IW_READ_ONLY=true.