mcp-wallet

Chain-agnostic MCP wallet interface for durable AI agents with autonomous transfers.

The durable agent runtime is the wallet principal: it can create wallets and independently prepare, sign, and broadcast supported transactions. Mnemonics and private keys remain inside encrypted local custody rather than crossing the model context.

Supported addresses

Related MCP server: mcp-server-insumer

Current scope

• Create and import accounts

• List accounts and derived addresses

• Show or delete an account

• AES-256-GCM encrypted mnemonic storage

• Agent-owned wallet creation through local MCP without exposing the mnemonic

• Native balance reads and autonomous native Ethereum, BNB Smart Chain, and HyperEVM transfers

• CAIP-2 chain identifiers and runtime capability discovery through a generic transfer interface

• Optional agent-configured policy safeguards; no mandatory human approval

• Local stdio MCP transport with no listening network port

• Chain-adapter boundary for future extensions

Not implemented: tokens, calldata, contract calls, swaps, bridges, Bitcoin/Solana/TRON transfers, HyperCore actions, indexed history, or automatic testnet selection.

Setup

Requirements: Linux with the util-linux flock command, and Node.js 22 or newer. Wallet and transfer state use kernel-managed advisory locks so crashes cannot leave stale ownership metadata or permit PID-reuse/ABA lock races.

npm install
npm run build

Generate a development master key without printing it:

export CRYPTO_MCP_MASTER_KEY="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('base64'))")"

Optional wallet-file override:

export CRYPTO_MCP_WALLET_FILE="$HOME/.crypto-mcp/wallet.json"

The default wallet file is $HOME/.crypto-mcp/wallet.json and is written with mode 0600.

Maintenance CLI

Create an account:

npm run wallet -- account create --label primary

The generated mnemonic is printed exactly once. Transfer it immediately to an appropriate offline backup or password manager; do not place it in shell history, logs, chat, source control, or MCP requests.

Import from stdin:

password-manager-command | npm run wallet -- account import --label imported

Manage public account data:

npm run wallet -- account list
npm run wallet -- account show <account-id>
npm run wallet -- account delete <account-id>

The CLI retains explicit lifecycle commands for debugging, recovery, and manual maintenance, but it is not part of the agent's authorization path:

npm run wallet -- transfer status <request-id>
npm run wallet -- transfer approve <request-id> --digest sha256:<digest>
npm run wallet -- transfer sign <request-id>
npm run wallet -- transfer broadcast <request-id>

Approval is bound to the account, chain ID, recipient, raw amount, nonce, fee fields, expiry, and idempotency key. Signing fails if any approved field changes.

Agent wallet MCP server

The local stdio server exposes exactly eight tools:

• create_wallet

• list_accounts

• get_account

• get_addresses

• get_wallet_capabilities

• get_balance

• send_transfer

• get_transfer_status

Start it with process-local wallet configuration:

npm run build
npm run mcp

An MCP client should launch node /absolute/path/to/mcp-wallet/dist/src/mcp/stdio.js and provide CRYPTO_MCP_MASTER_KEY and, optionally, CRYPTO_MCP_WALLET_FILE to that subprocess through external secret injection. Never put the master key in tool arguments, prompts, chat, source control, or ordinary configuration files.

create_wallet generates an encrypted wallet without returning its mnemonic. get_wallet_capabilities advertises the exact configured chains, assets, and operations. get_balance and send_transfer use CAIP-2 chain identifiers such as eip155:1 plus an explicit asset identifier; the current adapter supports only native. Generic tool names do not imply unsupported-chain support: unadvertised chains and assets fail closed. MCP cannot supply RPC URLs, policy overrides, nonces, calldata, raw signing payloads, mnemonics, or private keys, and sanitized results never expose raw signed transactions.

Transfer configuration

Each configured network defaults to full agent authority. Configure the owner-only transfer journal and RPC details in the MCP process environment—not tool arguments:

export CRYPTO_MCP_TRANSFER_FILE="$HOME/.crypto-mcp/transfers.json"
export CRYPTO_MCP_ETHEREUM_RPC_URL="https://your-rpc.example"
export CRYPTO_MCP_ETHEREUM_CHAIN_ID="1"
export CRYPTO_MCP_ETHEREUM_FEE_MODE="eip1559"

Equivalent BSC and HYPEREVM variables are supported. Fee mode must be eip1559 or legacy; chain ID is verified against eth_chainId before preparation. Use disposable accounts, test networks, bounded policy values, and non-production funds for initial validation.

An agent may opt into self-imposed safeguards by setting CRYPTO_MCP_TRANSFER_POLICY. Providing it switches to explicit policy configuration; omitted chains are disabled. Policies can set amount, fee, rolling 24-hour value, account, and recipient bounds. These are optional wallet-owner controls, not human approval requirements.

MCP usage examples

These are MCP tool arguments and structured results, not shell commands. Start the stdio server with process-local custody and network configuration before invoking transfer tools.

Create an agent-owned wallet

Tool: create_wallet

{
  "label": "primary-agent-wallet"
}

The result contains the account ID, label, creation time, and public addresses. It never contains the generated mnemonic or private keys.

Discover supported chains and assets

Tool: get_wallet_capabilities

{}

Example result for a configured Ethereum network:

{
  "chains": [
    {
      "chain": "eip155:1",
      "family": "evm",
      "assets": [{ "asset": "native", "decimals": 18 }],
      "operations": ["get_balance", "send_transfer", "get_transfer_status"]
    }
  ]
}

Only advertised chain and asset combinations are supported. For example, a configured Sepolia network is identified as eip155:11155111.

Read a balance

Tool: get_balance

{
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "asset": "native"
}

Example result:

{
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "asset": "native",
  "address": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
  "balance": "1.25",
  "balanceBaseUnits": "1250000000000000000",
  "decimals": 18
}

All amounts are decimal strings. Base-unit values are exact integer strings and are never converted through JavaScript floating point.

Send a transfer

Tool: send_transfer

{
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "asset": "native",
  "to": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
  "amount": "0.001",
  "maxFee": "0.0002",
  "idempotencyKey": "pay-invoice-2026-08-07-001"
}

The wallet autonomously validates, prepares, binds, signs, journals, broadcasts, and reconciles the transfer. Reusing the same idempotency key with the same request converges on the existing transfer; reusing it with different transfer details fails closed.

Example result fields:

{
  "id": "0190f502-f56d-7000-8000-000000000001",
  "state": "broadcast",
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "asset": "native",
  "to": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
  "amount": "0.001",
  "amountBaseUnits": "1000000000000000",
  "maxFeeBaseUnits": "200000000000000",
  "createdAt": "2026-08-07T00:00:00.000Z",
  "expiresAt": "2026-08-07T00:05:00.000Z",
  "transactionId": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Check transfer status

Tool: get_transfer_status

{
  "transferId": "0190f502-f56d-7000-8000-000000000001"
}

The result uses the same generic transfer shape. A confirmed transfer may also include blockReference; a terminal failure may include a bounded failureCode.

Development

npm run typecheck
npm test

The test suite derives its public BIP-39 vector from fixed entropy rather than storing a mnemonic phrase in repository fixtures.

Library API

import { JsonAccountStore, WalletAccountService } from "crypto-mcp";

const service = new WalletAccountService(
  new JsonAccountStore(walletFile),
  masterKey,
);

const accounts = await service.listAccounts();

MCP wallet creation and sending are autonomous. Secret import/export remains outside model-visible tools; MCP never accepts or returns mnemonics, seeds, private keys, master keys, or raw signed transactions.

See docs/security.md for the custody boundary and current limitations.