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 simulate, inspect, revalidate, 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 two-step native Ethereum, BNB Smart Chain, and HyperEVM transactions to ordinary code-less recipients outside reserved precompile/system address space; successful simulation must return empty call data

• Mandatory exact-transaction preflight with deterministic outflow reports and execution-time revalidation

• CAIP-2 chain identifiers and runtime capability discovery through a typed transaction 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, idempotency key, pinned simulation block, canonical outflows, completeness, and deterministic summary. Execution rechecks the pending nonce before and after exact re-simulation, then custody authenticates fresh evidence before signing. Signing and first submission reject stale, forged, or incomplete authorization.

Agent wallet MCP server

The local stdio server exposes exactly nine tools:

• create_wallet

• list_accounts

• get_account

• get_addresses

• get_wallet_capabilities

• get_balance

• simulate_transaction

• execute_transaction

• get_transaction_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 simulate_transaction use CAIP-2 chain identifiers such as eip155:1 plus an explicit typed operation; the current adapter supports only native transfers. simulate_transaction reserves the exact nonce, prepares exact fee and gas fields, pins an RPC block, runs eth_call, and returns canonical wallet outflows plus a bounded deterministic summary. execute_transaction accepts only that simulation ID and digest, rechecks the configured chain and policy, re-simulates the exact transaction at fresh chain state, and signs and broadcasts only if the preflight remains valid. Generic tool names do not imply unsupported-chain support: unadvertised chains, assets, and operations 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", "simulate_transaction", "execute_transaction", "get_transaction_status"],
      "transactionTypes": ["transfer"],
      "contractRecipients": false,
      "preflight": {
        "required": true,
        "completeness": "complete",
        "executionRevalidation": true
      }
    }
  ]
}

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.

Simulate a transaction

Tool: simulate_transaction

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

The wallet validates policy and balances, reserves the nonce, constructs the exact unsigned transaction, and simulates it at a pinned block. Reusing the same idempotency key with the same request converges on the existing transaction; changing any request field fails closed.

Example result:

{
  "requestId": "0190f502-f56d-7000-8000-000000000001",
  "state": "simulated",
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "operation": {
    "type": "transfer",
    "asset": "native",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "amount": "0.001",
    "amountBaseUnits": "1000000000000000"
  },
  "maxFeeBaseUnits": "200000000000000",
  "createdAt": "2026-08-07T00:00:00.000Z",
  "expiresAt": "2026-08-07T00:05:00.000Z",
  "preflight": {
    "simulationId": "0190f502-f56d-7000-8000-000000000001",
    "intentDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "status": "succeeded",
    "simulatedAt": "2026-08-07T00:00:00.000Z",
    "blockReference": "21900421",
    "blockHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "blockTimestamp": "1786060800",
    "simulationCompleteness": "complete",
    "summary": "Send 0.001 native asset units from 0x9858EfFD232B4033E47d90003D41EC34EcaEda94 to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on eip155:1. Maximum network fee: 0.000105 native asset units.",
    "outflows": [
      {
        "kind": "transfer",
        "from": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
        "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "asset": "native",
        "amount": "0.001",
        "amountBaseUnits": "1000000000000000",
        "certainty": "exact"
      },
      {
        "kind": "network_fee",
        "from": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
        "to": "network",
        "asset": "native",
        "amount": "0.000105",
        "amountBaseUnits": "105000000000000",
        "certainty": "maximum"
      }
    ],
    "warnings": []
  }
}

The summary is generated deterministically from the same canonical fields as outflows. simulationCompleteness: "complete" applies only to the currently supported native-transfer operation; it is not a claim that arbitrary contract effects can be inferred from eth_call.

Execute the reviewed simulation

Tool: execute_transaction

{
  "simulationId": "0190f502-f56d-7000-8000-000000000001",
  "intentDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
}

The digest binds the exact prepared transaction and preflight report, including the pinned block number, hash, and timestamp. Before signing, the wallet checks expiry, account and chain configuration, policy, and RPC chain ID, rejects block metadata more than 120 seconds old or more than 15 seconds in the future, then re-simulates the exact transaction at fresh pinned state. A missing, stale, reverted, malformed, incomplete, or digest-mismatched preflight fails closed. A successful result preserves the preflight, adds revalidatedAt, revalidationBlockReference, revalidationBlockHash, and revalidationBlockTimestamp, and eventually includes transactionId after signing and broadcast.

Check transaction status

Tool: get_transaction_status

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

The result uses the same transaction shape. A prepared report is exposed as state: "simulated"; a confirmed transaction 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 execution are autonomous: an agent can inspect the deterministic preflight and submit its digest without routine human approval. 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.