ceaser-mcp

MCP server for the Ceaser privacy protocol. Shield and unshield ETH privately on Base L2 using ZK proofs, directly from Claude Code or any MCP-compatible AI agent.

Quick Start

Claude Code (local, stdio)

claude mcp add --transport stdio ceaser -- npx -y ceaser-mcp

Or add to .mcp.json:

{
  "mcpServers": {
    "ceaser": {
      "command": "npx",
      "args": ["-y", "ceaser-mcp"],
      "env": {
        "CEASER_API_URL": "https://ceaser.org"
      }
    }
  }
}

Claude API Agents (remote HTTP)

{
  "mcp_servers": [{
    "type": "url",
    "url": "https://ceaser.org/mcp",
    "name": "ceaser"
  }]
}

Tools

Read-Only (6 tools)

| Tool | Description | |------|-------------| | ceaser_get_denominations | Valid deposit amounts with fee breakdown | | ceaser_get_fees | Fee calculation for any ETH amount | | ceaser_get_merkle_root | Current Merkle tree root | | ceaser_get_pool_info | Pool TVL, notes, fees | | ceaser_check_nullifier | Check if a nullifier is spent | | ceaser_get_status | Facilitator health and stats |

Shield (1 tool)

| Tool | Description | |------|-------------| | ceaser_shield_eth | Generate ZK proof + unsigned shield transaction |

Unshield (1 tool)

| Tool | Description | |------|-------------| | ceaser_unshield | Generate ZK proof + gasless withdrawal via facilitator |

Note Management (2 tools)

| Tool | Description | |------|-------------| | ceaser_list_notes | List stored privacy notes | | ceaser_import_note | Import a note from backup string |

How It Works

1. Shield: Agent generates a ZK proof locally, returns an unsigned transaction. User signs and sends from their wallet. A note (containing secrets) is stored locally. The unsigned TX is also saved to ~/.ceaser-mcp/pending-tx.json for auto-signing workflows.

2. Unshield: Agent loads the note, rebuilds the Merkle tree from the indexer, generates a burn ZK proof, and submits it to the facilitator for gasless settlement. No wallet needed.

3. Notes: Contain the secret and nullifier needed to spend shielded funds. Never transmitted over the MCP stream. Stored at ~/.ceaser-mcp/notes.json.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CEASER_API_URL | https://ceaser.org | Facilitator API base URL | | CEASER_CONTRACT_ADDRESS | 0x278652...BcD368 | zkWrapper contract address | | CEASER_CHAIN_ID | 8453 | Chain ID (Base mainnet) | | CEASER_CIRCUIT_URL | https://ceaser.org/circuits | Circuit artifact download URL | | CEASER_DATA_DIR | ~/.ceaser-mcp | Data directory for notes and cached circuits |

Architecture

• Local mode (stdio): Full 10 tools. Proof generation runs in-process via @noir-lang/noir_js + @aztec/bb.js.
• Remote mode (HTTP): Read-only 6 tools. Mounted at /mcp on the facilitator. No proof generation (too slow for HTTP timeouts).

Version Alignment

These versions must match the Ceaser contracts and frontend exactly:

| Package | Version | |---------|---------| | @aztec/bb.js | ^2.1.11 | | @noir-lang/noir_js | 1.0.0-beta.18 | | circomlibjs | ^0.1.7 |

License

MIT