crypto-mcp-server

A Model Context Protocol server that lets any MCP client (Claude Desktop, Cursor, etc.) perform EVM blockchain operations — reading balances, reading/writing contracts, simulating and sending transactions, and signing messages — through Alchemy RPC, using a wallet derived from a mnemonic or private key.

Features

• Multi-chain across Alchemy-backed networks. The target network is selectable per tool call (defaults to the configured DEFAULT_NETWORK).
  • Mainnets: ethereum, base, arbitrum, optimism, polygon
  • Testnets: sepolia, base-sepolia, arbitrum-sepolia, optimism-sepolia, polygon-amoy
• Both transports: stdio (default, for local clients) and Streamable HTTP (for remote/hosted use).
• Tools:
  • Reads: get_native_balance, get_token_balance, get_gas_price, get_block, get_transaction, resolve_ens, read_contract
  • Writes: send_native, send_token, write_contract
  • Pre-flight: simulate_transaction (dry-run, never broadcasts)
  • Signing: sign_message (EIP-191), sign_typed_data (EIP-712)

Prerequisites

• Node.js ≥ 18
• An Alchemy API key
• A wallet mnemonic or private key

Setup

npm install
cp .env.example .env   # then fill in the values
npm run build

Environment variables

Variable	Required	Description
ALCHEMY_API_KEY	yes	Your Alchemy API key. Used to build RPC endpoints for all chains.
MNEMONIC	one of	BIP-39 mnemonic phrase. Provide exactly one of this / key.
PRIVATE_KEY	one of	0x-prefixed hex private key. Provide exactly one.
DERIVATION_PATH	no	HD path used with MNEMONIC (defaults to ethers' default path).
DEFAULT_NETWORK	no	Default chain when a call omits network (mainnet or testnet, e.g. polygon-amoy, sepolia). Default: ethereum.
TRANSPORT	no	stdio (default) or http.
PORT	no	Port for the HTTP transport. Default: 3000.

The server fails to start (non-zero exit) if ALCHEMY_API_KEY is missing, if neither key is provided, or if both keys are provided.

Running

stdio (default — most MCP clients launch the server this way):

npm run start
# or for development with reload:
npm run dev

Streamable HTTP:

TRANSPORT=http PORT=3000 npm run start
# MCP endpoint: http://localhost:3000/mcp

Using with an MCP client (stdio)

Add to your client's MCP config (e.g. Claude Desktop's claude_desktop_config.json, or .cursor/mcp.json). See examples/mcp-client-config.json.

{
  "mcpServers": {
    "crypto": {
      "command": "node",
      "args": ["/absolute/path/to/crypto-mcp-server/dist/index.js"],
      "env": {
        "ALCHEMY_API_KEY": "your-alchemy-key",
        "PRIVATE_KEY": "0xyour-private-key",
        "DEFAULT_NETWORK": "ethereum"
      }
    }
  }
}

Security

This server can spend funds. It holds a mnemonic or private key in process memory and can sign and broadcast transactions.

• Secrets are read only from environment variables and are never logged, echoed, or returned in tool outputs or error messages.
• Prefer simulate_transaction before any send_* / write_contract call to preview gas and catch reverts.
• The HTTP transport exposes spend operations over the network. It performs no authentication of its own — run it only behind a trusted network and/or an authenticating proxy. For local single-user use, prefer stdio.
• Use a dedicated, low-value wallet. Never point this at a key holding significant funds without your own additional controls.

Development

npm run lint   # type-check only (tsc --noEmit)
npm run test   # vitest
npm run build  # compile to dist/