monad-mcp

MCP server for the Monad blockchain. Your agent's gateway to balances, transfers, swaps, and DeFi on Monad — with signing handled by a Privy embedded wallet, never by the agent.

Built around a simple shape — stored requests + approval URLs + skill plugins — on Monad mainnet 143 / testnet 10143, with Privy as the wallet provider.

🌐 Landing page + live read-only demo: pareen.github.io/monad-mcp — query real Monad balances in your browser, exactly what the agent sees.

🔌 Connect it — no install, no terminal. In Claude Desktop or ChatGPT, add a custom connector and paste this URL:

https://monad-mcp.fly.dev/mcp

That's the whole setup — read tools (balances, prices, portfolios, token checks) work immediately. Step-by-step for each app: docs/connect-claude.md.

Prefer the terminal? One line in Claude Code:

claude mcp add --transport http monad https://monad-mcp.fly.dev/mcp   # hosted
claude mcp add monad -- npx -y monad-mcp                              # or run it locally

The hosted endpoint runs in split mode: read tools are public (paste the URL, no login — safe to share) and write tools are gated behind a Privy sign-in, returning auth_required until you authenticate. The hosted sign-in path is wired but still being verified end-to-end, so the tested route for transactions is your own Privy-signed instance — see docs/connect-claude.md, docs/FAQ.md for common security/setup questions, and docs/DEPLOY.md.

🧭 Monad ≠ Ethereum: the server ships agent-facing guidance on Monad's quirks (128 KB contracts, gas_limit billing, speculative latest, eth_getLogs caps, FastLane/MEV) as monad://guide/* MCP resources — see docs/building-on-monad.md.

What's in the box

Core tools (work on any address; auth required only where noted):

Skill plugins (additive, drop in your own under src/plugins/):

• Uniswap (uniswap_quote, uniswap_swap, approve_erc20) — exact-input single-hop swaps on Uniswap v3 (testnet + mainnet).
• Kintsu (kintsu_stake, kintsu_request_unstake, kintsu_claim_unstake, kintsu_position) — liquid staking MON → sMON via Kintsu's ERC-7535 vault. Two-step unstake with batch processing.
• FastLane (fastlane_stake, fastlane_unstake, fastlane_position) — liquid staking MON → shMON via FastLane's shMONAD ERC-4626 vault. Payable native deposit, synchronous redeem (no epoch wait); shMON keeps earning staking + MEV rewards.
• Morpho (morpho_supply, morpho_withdraw, morpho_borrow, morpho_repay, morpho_position, morpho_market) — lending on Morpho Blue's singleton. Caller passes MarketParams inline; plugin derives the market id.
• Kuru (kuru_best_bid_ask, kuru_market_params, kuru_place_limit, kuru_cancel_orders, kuru_market_swap) — fully-on-chain CLOB. Ships with known mainnet markets (MON/USDC, MON/AUSD, WETH/USDC); accepts raw addresses for new ones.

All write tools across plugins auto-route through a covering session-key grant (see "Session keys" below); otherwise they return an approval URL.

Mainnet-only plugins (Kintsu / FastLane / Morpho / Kuru) are skipped at boot when MONAD_DEFAULT_NETWORK=testnet. Override per-tool with network: "mainnet".

Quickstart

1. Install + configure

git clone https://github.com/you/monad-mcp.git
cd monad-mcp
npm install
cp .env.example .env

Edit .env. Minimum config to do anything useful with write tools:

PRIVY_APP_ID=clxxxxxxxxxxx          # from https://dashboard.privy.io
PRIVY_APP_SECRET=...                # from the same place
PRIVY_VERIFICATION_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"  # optional but recommended

# Where this server is reachable from a browser (used in approval URLs).
PUBLIC_BASE_URL=http://localhost:8787
PORT=8787

# Which Monad network to default to when a tool call omits `network`.
MONAD_DEFAULT_NETWORK=testnet

For the Uniswap plugin, supply contract addresses (verify against the canonical Uniswap deployment for Monad before using):

UNISWAP_MAINNET_QUOTER_V2=0x...
UNISWAP_MAINNET_SWAP_ROUTER_02=0x...
UNISWAP_TESTNET_QUOTER_V2=0x...
UNISWAP_TESTNET_SWAP_ROUTER_02=0x...

2. Privy app setup

In the Privy dashboard:

1. Create an app. Enable embedded wallets under "Wallets".
2. Under "Networks", add Monad mainnet (chainId 143) and/or testnet (chainId 10143) as an EVM chain.
3. Copy the App ID + App Secret into .env.
4. Copy the JWT verification key (PEM-encoded ES256 public key) into PRIVY_VERIFICATION_KEY for fastest token verification. If omitted, the server falls back to JWKS over the network.
5. (Optional) Configure wallet policies (spend limits, allowlists) to gate what the agent can do.

2a. Bootstrap server-side wallet authorization (one-time)

Privy embedded wallets are user-owned by default — the server cannot sign for them. The MCP server needs a P-256 key quorum registered with Privy, attached as an additional_signer on every wallet it provisions. Bootstrap it:

npm run bootstrap:auth-key
# Generates a P-256 keypair, registers it as a Privy key quorum, prints two env vars.
# Paste PRIVY_AUTHORIZATION_PRIVATE_KEY and PRIVY_KEY_QUORUM_ID into .env.

After bootstrap, every create_user call attaches the quorum at wallet creation, and every transfer/swap includes the private key in authorization_context. Important: wallets minted before you set these env vars are stranded — Privy doesn't let you retrofit an additional_signer (updating authorization requires existing authorization). Always bootstrap first.

3. Run

# Stdio mode for Claude Desktop, Cursor, etc.
npm run build
npm start

# HTTP / Streamable HTTP mode for remote MCP clients (Claude Web, ChatGPT).
npm run start:http
# Server listens on http://localhost:8787/mcp

4. Wire it into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json. The --env-file flag loads PRIVY_*, MONAD_*, and PUBLIC_BASE_URL from your .env into the spawned process:

{
  "mcpServers": {
    "monad": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/monad-mcp/.env",
        "/absolute/path/to/monad-mcp/dist/index.js"
      ]
    }
  }
}

You'll also need the HTTP server running (npm run start:http) for the approval flow — the stdio MCP returns approval URLs that point at the HTTP server. See docs/claude-desktop.md for the full dogfood walkthrough (bootstrap, funding, first transfer).

Public reads, no self-hosting: to use the read tools (balances, portfolio, history) without building anything, point Claude Desktop at the hosted endpoint via the mcp-remote shim — "args": ["-y", "mcp-remote", "https://monad-mcp.fly.dev/mcp"]. Writes (transfers/swaps) are gated behind a Privy sign-in; the verified path for them is a self-hosted signer.

5. Try a prompt

What's the balance of 0x000…0000 on Monad testnet?
Send 0.01 MON to 0xabc… on Monad testnet.