Setup MCP

Install and configure the IronWallet MCP server for Cursor, Claude Code, Codex, Grok, 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.

Features

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.

Tools

Tool

Purpose

Moves funds?

list_wallets

Wallet names, addresses, and policy

accept_mcp_consent

Record chat acceptance of the MCP disclaimer

create_wallets

Create wallets; returns a browser backup_url

open_wallet_manager

Local browser UI to import / create / back up

set_wallet_policy

Replace per-wallet limits (readOnly, maxPerTxUsd, allow-list)

get_deposit_qr

Deposit QR as PNG plus a local qr_url

get_balance

Native or token balance

estimate_transfer

Fee estimate, no broadcast

send_transfer

Sign locally and send

yes

get_operation_status

Poll a transfer

list_swap_networks

Networks available for swap

list_swap_assets

Sell / buy catalog (symbols, addresses, decimals)

estimate_swap

Swap quote (may expire)

execute_swap

Fresh quote → sign → swap

yes

get_swap_status

Poll a swap

No tool accepts or returns a seed phrase. Import and backup happen only in the local browser (open_wallet_manager / backup_url).

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.

Installation

Option 1: npx (recommended)

Use npx to run the server without global installation. This ensures you always use the latest version.

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

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.

npm install -g @ironwallet/mcp-server@latest

Setup guides

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.

Cursor

Open in Cursor

Install once. After that, the wallet tools are available in every chat. You can also paste this into ~/.cursor/mcp.json and restart Cursor.

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Reload Cursor after install so PATH includes npx.

Standalone page for Cursor — one HTTP fetch returns only this guide.

Claude Code

Open in Claude Code

Run these commands in order:

1claude plugin marketplace add ironwallet/ironwallet-agent-kit

2claude plugin install ironwallet-mcp@ironwallet

After plugin install, wait ~45 seconds and start a new chat so the tools load.

Or point Claude Code at the stdio server directly:

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Standalone page for Claude Code — one HTTP fetch returns only this guide.

VS Code

Open in VS Code

Opens VS Code and registers the local MCP server. You can also add this to your VS Code MCP settings (user or workspace).

2 "mcp": {

3 "servers": {

4 "ironwallet": {

5 "type": "stdio",

6 "command": "npx",

7 "args": ["-y", "@ironwallet/mcp-server"]

8 }

9 }

10 }

11}

Standalone page for VS Code — one HTTP fetch returns only this guide.

Codex

Open in Codex

Run these commands in order, then reload so the MCP tools are available.

1codex plugin marketplace add ironwallet/ironwallet-agent-kit

2codex plugin add ironwallet-mcp@ironwallet

Or point Codex at the stdio server directly:

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Standalone page for Codex — one HTTP fetch returns only this guide.

Grok

Install via the plugin marketplace:

1grok plugin marketplace add ironwallet/ironwallet-agent-kit

2grok plugin install ironwallet-mcp --trust

Standalone page for Grok — one HTTP fetch returns only this guide.

Other clients

Use the stdio transport. Point your MCP client to:

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Standalone page for Other clients — one HTTP fetch returns only this guide.

First run & wallet setup

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:

Consent. Before creating or importing a wallet, the agent shows the MCP disclaimer in chat and records your acceptance (accept_mcp_consent), or you press Continue in the wallet manager.

Create or import. 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.

Fund the wallet. Ask the agent for a deposit QR (get_deposit_qr) or an address (list_wallets) and send a small amount. Keep the balance limited — this is a hot wallet.

Data on disk

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.

Environment variables

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:

Variable

Description

Default

IW_READ_ONLY

Reject send_transfer and execute_swap process-wide. Distinct from per-wallet policy.readOnly

false

IW_KEYSTORE_DIR

Keystore directory

~/.ironwallet-mcp

IW_PASSPHRASE

Override the keystore wrapping secret

generated locally

IW_RELAY_API_KEY

Override the relay API key

generated UUID

IW_HTTP_TIMEOUT_MS

General HTTP timeout

15000

IW_HTTP_FORWARD_TIMEOUT_MS

Timeout for broadcast-style calls. A client timeout does not always mean the operation failed — check status

60000

IW_LOG_ENABLED

JSONL diagnostics to a log file (0 to disable)

IW_LOG_LEVEL

debug / info / warn / error

info

Security

Seeds 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.

Testing

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 @modelcontextprotocol/inspector npx -y @ironwallet/mcp-server

Troubleshooting

The MCP client times out on first start

npx downloads the package on first run, which can take ~30 seconds.

Run npx -y @ironwallet/mcp-server once in a terminal to warm the cache, then reconnect.
Or install globally: npm install -g @ironwallet/mcp-server@latest.

Tools don’t show up in the client

Check Node.js 20+ is installed: node --version.
Reload the client after install so PATH includes npx.
After a plugin install (Claude Code / Codex / Grok), start a new chat so the tools load.
Verify the config file contains valid JSON and restart the client.
Test the server manually with the MCP inspector (see Testing).

`create_wallets` returns `needs_consent`

The 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 transfer or swap timed out

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.

A send or swap is rejected

Check 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.
Check whether the server runs with IW_READ_ONLY=true.

Setup MCP

Features

Tools

Installation

Setup guides

Cursor

Claude Code

VS Code

Codex

Grok

Other clients

First run & wallet setup

Data on disk

Environment variables

Security

Testing

Troubleshooting

The MCP client times out on first start

Tools don’t show up in the client

create_wallets returns needs_consent

A transfer or swap timed out

A send or swap is rejected

Related

`create_wallets` returns `needs_consent`