Zama fhEVM MCP Server

npm: @just-jelly/mcp-server — v2.2.5

A production-grade Model Context Protocol (MCP) server that gives AI coding agents 34 real tools for building confidential smart contracts on Zama's fhEVM.

Instead of guessing, your AI can scaffold projects, compile and deploy contracts, check wallet balances, look up all Sepolia protocol addresses, interact with confidential token wrappers, encrypt values, check ACL permissions, run tests, decode errors, and learn fhEVM through step-by-step tutorials — all from chat.

Install & Run

# Run directly (no install needed)
npx -y @just-jelly/mcp-server

# Or install globally
npm install -g @just-jelly/mcp-server

Connect to Your AI Tool

Two config fields you always need

"env": {
  "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
  "FHEVM_RPC_URL":     "https://eth-sepolia.public.blastapi.io"
}

Security: Use a dedicated deployer wallet with testnet ETH only — never your main wallet.

Tip — avoid hardcoding: If you prefer not to paste your key into a config file, set it as a shell env var first and reference it from a wrapper script (see Avoiding hardcoded keys below).

Both fields are optional for read-only tools (code generation, tutorials, error decoding). They are required for deploy_contract, check_wallet_balance, and any tool that sends transactions.

Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fhevm": {
      "command": "npx",
      "args": ["-y", "@just-jelly/mcp-server"],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.public.blastapi.io",
        "ETHERSCAN_API_KEY": "optional_for_auto_verification"
      }
    }
  }
}

Restart Claude Desktop → you'll see a 🔨 hammer icon in chat.

Claude Code (terminal CLI)

claude mcp add fhevm -- npx -y @just-jelly/mcp-server
claude mcp set-env fhevm FHEVM_PRIVATE_KEY  0x_your_deployer_private_key
claude mcp set-env fhevm FHEVM_RPC_URL      https://eth-sepolia.public.blastapi.io

Or edit ~/.claude.json directly with the full config block above.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "fhevm": {
      "command": "npx",
      "args": ["-y", "@just-jelly/mcp-server"],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.public.blastapi.io"
      }
    }
  }
}

Then: Cursor Settings → Features → MCP → Enable → Reload.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "fhevm": {
      "command": "npx",
      "args": ["-y", "@just-jelly/mcp-server"],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.public.blastapi.io"
      }
    }
  }
}

OpenAI Codex CLI

Edit ~/.codex/config.json:

{
  "mcpServers": {
    "fhevm": {
      "command": "npx",
      "args": ["-y", "@just-jelly/mcp-server"],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.public.blastapi.io"
      }
    }
  }
}

Cline (VS Code)

Open VS Code → Cline sidebar → Settings → MCP Servers → Add:

• Command: npx
• Args: -y @just-jelly/mcp-server
• Env: add FHEVM_PRIVATE_KEY and FHEVM_RPC_URL

Avoiding hardcoded keys

If you don't want your private key in a JSON config file, use a small wrapper script that reads it from your shell environment:

~/fhevm-mcp.sh:

#!/bin/bash
# Reads FHEVM_PRIVATE_KEY and FHEVM_RPC_URL from your shell profile
exec npx -y @just-jelly/mcp-server

Then in your MCP config:

{
  "mcpServers": {
    "fhevm": {
      "command": "/bin/bash",
      "args": ["${HOME}/fhevm-mcp.sh"]
    }
  }
}

And in your ~/.zshrc / ~/.bashrc:

export FHEVM_PRIVATE_KEY="0x_your_deployer_private_key"
export FHEVM_RPC_URL="https://eth-sepolia.public.blastapi.io"

This way the key only ever lives in your shell profile — never in a project file.

Environment Variables

| Variable | Required | Purpose | |---|---|---| | FHEVM_PRIVATE_KEY | For deploy/test | 0x... deployer wallet key (set in MCP config env block) | | FHEVM_RPC_URL | Optional | Override default Sepolia RPC endpoint | | ETHERSCAN_API_KEY | For verify_on_etherscan | Get free key at etherscan.io/myapikey |

These live in the MCP config env block — you never need a .env file in your project. Every deploy/test tool automatically forwards them to Hardhat subprocesses.

34 Available Tools

Meta

| Tool | What It Does | |---|---| | list_tools | List all 31 tools with descriptions. Call this first. |

Wallet & Config (new in v2.1.0)

| Tool | What It Does | |---|---| | setup_mcp_config | Generate exact JSON config for Claude/Cursor/Windsurf/Codex/Cline — shows where to put your keys | | check_wallet_balance | Check ETH balance — derives address from FHEVM_PRIVATE_KEY if no address given | | get_faucet_links | All 5 Sepolia faucets with daily limits, requirements, and links |

Protocol Addresses (new in v2.1.0)

| Tool | What It Does | |---|---| | get_protocol_addresses | Full Sepolia address book: core fhEVM, Zama tokens, all 8 confidential wrappers, staking, governance, fees | | verify_on_etherscan | Verify deployed contract source on Etherscan (uses ETHERSCAN_API_KEY from config) | | watch_decryption_callback | Polling script + test pattern to wait for FHE.requestDecryption() callbacks | | get_confidential_wrapper_code | Complete TypeScript for cUSDCMock/cUSDTMock/cWETHMock/cZAMAMock: mint→wrap→transfer→balance |

Project Setup

| Tool | What It Does | |---|---| | scaffold_fhevm_project | Create a complete Hardhat project — 4 templates: minimal, token, voting, auction | | generate_hardhat_config | Generate hardhat.config.ts with correct evmVersion, networks, optional extras | | generate_vite_config | Generate Vite config with REQUIRED CORS headers for fhEVM WASM | | check_dependencies | Scan package.json for common fhEVM dependency errors (chai v5, missing plugin) |

Compile & Deploy

| Tool | What It Does | |---|---| | compile_solidity | Compile contracts with fhEVM-specific error explanations | | deploy_contract | Deploy to Sepolia or localhost — FHEVM_PRIVATE_KEY from config forwarded automatically | | run_hardhat_tests | Run tests with fhEVM failure analysis (mock + Sepolia modes) |

Code Generation

| Tool | What It Does | |---|---| | generate_confidential_contract | Generate full contracts — 8 patterns: token/vault/voting/auction/payroll/lending/identity/game | | generate_fhevm_test | Test boilerplate with encrypt/decrypt patterns | | generate_frontend_dapp | Complete React dApp with WASM setup, balance reveal, transfer UI |

Encryption

| Tool | What It Does | |---|---| | encrypt_value | Generate full frontend + Node.js encryption code for any type | | encrypt_multiple_values | Pack multiple values into one input proof (gas efficient) | | get_encrypted_balance | Read handle from contract + complete re-encryption frontend code | | read_contract_state | Call any view function on a deployed contract |

ACL

| Tool | What It Does | |---|---| | check_acl_permission | Live ACL check on Sepolia — is this address allowed to use this handle? | | explain_acl_pattern | Production Solidity code for 6 ACL scenarios |

Analysis & Errors

| Tool | What It Does | |---|---| | verify_fhevm_contract | Static analysis — finds fhEVM bugs before deployment | | decode_fhevm_error | Decode any fhEVM error → root cause + exact fix (30+ patterns) |

Network & Gas

| Tool | What It Does | |---|---| | get_network_config | All Sepolia/mainnet addresses + SDK initialization code | | estimate_fhe_gas | Gas cost model + optimization strategies |

Tutorials

| Tool | What It Does | |---|---| | get_fhevm_tutorial | Step-by-step tutorials: quickstart, confidential-token, voting, frontend, re-encryption, on-chain-decryption, testing, deployment, OpenZeppelin | | explain_fhe_type | Deep reference for every FHE type — euint8→256, ebool, eaddress, casting, ops table | | explain_coprocessor | Architecture diagram, async flow, gas model, mock vs Sepolia comparison |

Example Session

You: Set up this MCP server in Cursor

AI: [setup_mcp_config({ tool: "cursor" })]
    Here's your .cursor/mcp.json — paste your FHEVM_PRIVATE_KEY in the env block.
    Run check_wallet_balance after to confirm it's working.

You: Create a confidential token project called SecretCoin

AI: [scaffold_fhevm_project]
    ✅ Created ./secret-coin/ with:
       contracts/SecretCoin.sol
       test/SecretCoin.test.ts
       scripts/deploy.ts
       hardhat.config.ts (evmVersion: cancun ✓)

You: Deploy to Sepolia

AI: [compile_solidity → deploy_contract]
    ✅ Deployed: 0x1234...5678
       https://sepolia.etherscan.io/address/0x1234...5678

You: Verify it on Etherscan

AI: [verify_on_etherscan({ contractAddress: "0x1234...5678" })]
    ✅ Verified — view source at etherscan.io/...

You: What confidential tokens are live on Sepolia?

AI: [get_protocol_addresses({ category: "confidential-wrappers" })]
    cUSDCMock: 0x7c5BF... (underlying: mintable USDC mock)
    cUSDTMock: 0x4E7B...
    cWETHMock: 0x4620...
    ... (8 wrappers total)

You: I'm getting "ACL: Not allowed"

AI: [decode_fhevm_error]
    Root cause: Missing FHE.allowThis() after ciphertext assignment.
    Fix: Add FHE.allowThis(_balances[user]) immediately after every = assignment.

Build from Source

git clone https://github.com/juSt-jeLLy/zama-fhevm-skill
cd zama-fhevm-skill/mcp-server

pnpm install
pnpm run build

# Test it
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
| node dist/index.js

License

BSD-3-Clause-Clear — same as Zama's fhEVM codebase.