celo-mcp
artugrande/celo-mcp
Open-source remote MCP server for Celo — read+write access for any LLM. Unsigned-tx writes (no key custody), ERC-8004 agent identity, x402 payments.
Instalação
npx convez-ai artugrande/celo-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Celo MCP
Read + write access to Celo for any LLM — over a single remote URL. Balances, sends, swaps, agent identity + reputation (ERC-8004), and x402 micropayments. Writes return unsigned transactions — the server never holds a key or broadcasts anything.
The official
celo-org/celo-mcpis Python, local-stdio, and read-only. This is the first TypeScript, remote (Vercel-hosted), write-enabled Celo MCP — zero install, add a URL.
Connect
Add the Streamable-HTTP MCP endpoint to Claude Desktop, Cursor, or any MCP client:
{
"mcpServers": {
"celo": { "url": "https://<your-deployment>.vercel.app/mcp" }
}
}
The landing page itself has a live in-browser chat (Vercel AI SDK + AI Gateway) wired to the same tools — try it at the deployment root.
Tools
| Tool | Does |
|---|---|
get_balance | Native CELO + stablecoin balances for an address |
get_token_info | Verified address, decimals, type for a token symbol/alias |
resolve_address | Validate + checksum a Celo/EVM address |
build_send_tx | Unsigned CELO/ERC-20 transfer tx |
build_swap_tx | Uniswap v3 quote + unsigned approval & swap txs |
agent_identity | ERC-8004 agent lookup by agentId: owner, metadata, wallet, reputation |
x402_pay | Fetch an x402 URL, parse the 402 challenge, build the unsigned stablecoin payment |
list_capabilities | Self-describing manifest: chain, tools, tokens, signing model |
No key custody
Every write tool returns { chainId, to, data, value } for the user's wallet/agent to
sign and broadcast. There is no private key anywhere in this server.
Supported tokens
CELO, USDm (cUSD), EURm (cEUR), BRLm (cREAL), USDC, USDT, and Mento regional stables
(KESm, NGNm, COPm, GHSm, ZARm). All addresses are verified from Celo docs in
lib/tokens.ts and lib/contracts.ts.
Environment
| Var | Purpose | Default |
|---|---|---|
CELO_RPC_URL | Celo mainnet RPC | https://forno.celo.org |
AI_GATEWAY_API_KEY | Powers the /demo chat only | — (required for demo) |
No key is needed for the MCP tools themselves — reads use a public RPC, writes are unsigned.
Local development
npm install
npm run dev # http://localhost:3000 (MCP endpoint at /mcp)
Inspect the MCP server:
npx @modelcontextprotocol/inspector
# Streamable HTTP → http://localhost:3000/mcp → List Tools
Tests
npm run test # vitest — pure tool functions with a mocked viem client
Deploy
npx vercel --prod
Set AI_GATEWAY_API_KEY in the Vercel dashboard (and CELO_RPC_URL if not using Forno).
The MCP endpoint is then live at https://<deployment>.vercel.app/mcp.
Architecture / self-host (stdio)
Each tool in lib/tools/ is a pure, dependency-injected function with a zod
input and a typed result — no MCP/HTTP coupling. app/[transport]/route.ts wires them into
mcp-handler; the /demo chat imports the same functions as AI SDK tools. To self-host a
local stdio server, wrap those functions in an @modelcontextprotocol/sdk stdio server —
the tool logic is untouched.
License
MIT