code-mode-alchemy-mcp

An MCP (Model Context Protocol) server that gives Claude access to Alchemy's blockchain APIs. Instead of defining 88+ individual tools, it loads all Alchemy API specs at startup and exposes just two tools — search and execute — keeping context usage minimal (~1,000 tokens vs. thousands).

Inspired by Cloudflare's Code Mode MCP pattern.

How It Works

At startup, the server fetches 10 Alchemy API specifications (6 REST OpenAPI + 4 JSON-RPC OpenRPC) and indexes all their endpoints. Claude can then:

1. Search — find relevant endpoints by keyword
2. Execute — run JavaScript code in a sandboxed environment against those endpoints

Claude → search("NFT owner") → finds getNFTsForOwner endpoint
Claude → execute(code)       → runs against Alchemy API, returns data

Loaded Specifications

REST (OpenAPI):

• nft — NFT operations (mint, transfer, ownership queries)
• portfolio — Wallet portfolio data
• prices — Token pricing information
• notify — Webhook notifications
• transactions — Transaction history and details
• accounts — Account management

JSON-RPC (OpenRPC):

• transfers — Token transfer history (alchemy_getAssetTransfers)
• token — Token metadata and balances (alchemy_getTokenBalances, etc.)
• transaction-simulation — Simulate transactions before sending
• bundler — ERC-4337 bundler operations

Prerequisites

• Node.js 18+
• An Alchemy API key

Installation

git clone https://github.com/your-username/code-mode-alchemy-mcp
cd code-mode-alchemy-mcp
npm install
npm run build

Configuration

Copy the example environment file:

cp .env.example .env

Set your values in .env:

ALCHEMY_API_KEY=your_key_here
ALCHEMY_NETWORK=eth-mainnet

Supported Networks

Any network string Alchemy supports in their URL format, e.g.:

• eth-mainnet
• eth-sepolia
• polygon-mainnet
• arb-mainnet
• opt-mainnet
• base-mainnet

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "alchemy": {
      "command": "node",
      "args": ["/absolute/path/to/code-mode-alchemy-mcp/dist/index.js"],
      "env": {
        "ALCHEMY_API_KEY": "your_key_here",
        "ALCHEMY_NETWORK": "eth-mainnet"
      }
    }
  }
}

Restart Claude Desktop. You should see the Alchemy MCP server connected.

Tools

search(query, limit?)

Searches across all loaded endpoint metadata (summaries, descriptions, paths, tags) and returns the most relevant endpoints.

Parameter	Type	Default	Description
query	string	required	Keywords to search for
limit	number	8	Max results to return (max 20)

Example queries:

• "NFT owner" — find endpoints for fetching NFTs by owner
• "token balance" — find token balance endpoints
• "asset transfers" — find transfer history endpoints
• "simulate transaction" — find simulation endpoints

execute(code)

Runs JavaScript code in a sandboxed Node.js VM with access to the Alchemy API. Execution is isolated with a 30-second timeout.

Available in the sandbox:

Name	Type	Description
request(url, params?, options?)	function	Simplified API caller. Replaces {apiKey} and {network} in the URL automatically.
fetch	function	Raw Fetch API for custom requests
ALCHEMY_API_KEY	string	Your API key
ALCHEMY_NETWORK	string	Your configured network
console.log	function	Output captured and returned
console.error	function	Errors captured and returned

REST example:

const data = await request(
  "https://{network}.g.alchemy.com/nft/v3/{apiKey}/getNFTsForOwner",
  { owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", withMetadata: true }
);
return data;

JSON-RPC example:

const data = await request(
  "https://{network}.g.alchemy.com/v2/{apiKey}",
  {
    jsonrpc: "2.0",
    method: "alchemy_getTokenBalances",
    params: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
    id: 1
  },
  { method: "POST" }
);
return data;

Usage Examples

NFTs for a wallet

"Show me all NFTs owned by 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Claude will:

1. Call search("NFT owner") → finds getNFTsForOwner
2. Call execute(...) → fetches and returns NFT data

Token balances

"What ERC-20 tokens does this address hold: 0x..."

Claude will:

1. Call search("token balances") → finds alchemy_getTokenBalances
2. Call execute(...) → returns token list with balances

Transaction history

"Show recent transactions for vitalik.eth"

Claude will:

1. Call search("asset transfers") → finds alchemy_getAssetTransfers
2. Call execute(...) → returns transfer history

Simulate a transaction

"What would happen if I sent 1 ETH from 0x... to 0x...?"

Claude will:

1. Call search("simulate transaction") → finds simulation endpoint
2. Call execute(...) → returns simulation result

Development

# Run in development mode (no build step needed)
npm run dev

# Build for production
npm run build

# Run the compiled server
npm start

Project Structure

code-mode-alchemy-mcp/
├── src/
│   └── index.ts        # Everything: spec loading, search, sandbox, MCP server
├── dist/
│   ├── index.js        # Compiled output (run this)
│   └── index.d.ts      # TypeScript declarations
├── .env.example        # Environment variable template
├── package.json
└── tsconfig.json

Architecture

Claude Desktop
     │
     │  MCP (stdio)
     ▼
MCP Server
     │
     ├── Startup: fetch 10 specs → index all endpoints
     │
     ├── search(query)
     │     └── score & rank endpoints by keyword match
     │
     └── execute(code)
           └── vm.runInNewContext() with 30s timeout
                 └── request() helper → Alchemy REST/RPC APIs

Why two tools instead of 88+?

Defining every Alchemy endpoint as a separate MCP tool would consume thousands of tokens just in tool definitions, before Claude even starts reasoning. This pattern loads specs once, searches them dynamically, and executes code — using ~1,000 tokens of tool definitions regardless of how many endpoints Alchemy adds.

Security Notes

• Code in execute() runs in a Node.js vm sandbox with no access to the filesystem, environment, or require
• The API key is injected by the sandbox via placeholder replacement — it is never returned in search results or exposed to user-visible output
• Execution is limited to 30 seconds to prevent runaway code

References

• Cloudflare Code Mode MCP — the pattern this is based on
• Cloudflare Agents API Reference
• Alchemy OpenAPI Specs
• Model Context Protocol
• Alchemy API Docs

License

MIT