crypto-mcp

crypto-mcp

Minimal multichain wallet account core with a read-only MCP server.

This implementation manages local accounts, encrypts one BIP-39 mnemonic per account, and derives public addresses without network access.

Supported addresses

Current scope

• Create and import accounts
• List accounts and derived addresses
• Show or delete an account
• AES-256-GCM encrypted mnemonic storage
• Operator-only CLI
• Read-only local stdio MCP server
• Chain-adapter boundary for future extensions

Not yet implemented: balances, history, transactions, signing, broadcasting, RPC access, or testnet selection.

Setup

Requirements: Node.js 22 or newer.

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.

Operator 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>

Safe MCP server

The local stdio server exposes exactly three deterministic, read-only tools:

• list_accounts
• get_account
• get_addresses

Start it with process-local wallet configuration:

npm run build
npm run mcp

An MCP client should launch node /absolute/path/to/crypto-mcp/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.

Account creation, mnemonic import, and deletion remain operator CLI operations. The MCP server has no tools for these actions and exposes no mnemonic, private-key, signing, transaction, RPC, balance, or history capability.

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();

Mnemonic creation, import, and account deletion remain operator-controlled. MCP tools accept only account IDs and expose public information; they never accept or return mnemonics.

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