Celo MCP Server

The Celo MCP Server gives AI assistants and editors read access to Celo — blocks, transactions, token balances, gas fees, governance proposals, staking and validator data. It runs locally over stdio, or as a remote endpoint over Streamable HTTP. Every tool is a query. The server never signs or sends a transaction, so it cannot move funds. To give an agent a wallet, see Celina.

What it covers

Network status, blocks and transactions
CELO, ERC-20 and Mento stablecoin balances for any address
EIP-1559 gas fee data
Governance proposals and proposal details
Staking balances, activatable stakes, validator groups and network-wide staking metrics

Prerequisites

Python 3.11 or higher
An MCP-capable client — VS Code, Cursor, Claude Desktop, Claude Code, Windsurf or a JetBrains IDE

Install

pipx install celo-mcp

uvx celo-mcp also works and needs no install step; the client configurations below use it.

The server always reads from Celo Mainnet at https://forno.celo.org. The RPC endpoint is not configurable in the current release — the client is constructed without arguments, so neither CELO_RPC_URL nor the CELO_MCP_-prefixed settings reach it. There is no testnet mode.

Connect your client

VS Code
Cursor
Claude Desktop
Claude Code
Windsurf & JetBrains

VS Code reads .vscode/mcp.json in your workspace, or the user-level file opened with MCP: Open User Configuration from the command palette. The key is servers, not mcpServers:

{
  "servers": {
    "celo-mcp": {
      "command": "uvx",
      "args": ["--refresh", "celo-mcp"]
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "celo-mcp": {
      "command": "uvx",
      "args": ["--refresh", "celo-mcp"]
    }
  }
}

--refresh makes uvx re-resolve the package so you pick up new releases.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "celo-mcp": {
      "command": "uvx",
      "args": ["--refresh", "celo-mcp"]
    }
  }
}

claude mcp add celo-mcp -- uvx --refresh celo-mcp

Both configure MCP servers through their own settings UI rather than a file you edit directly. Use uvx as the command and --refresh celo-mcp as the arguments.

Try it:

Using the Celo MCP server, what is the current gas fee data on Celo mainnet?

Available tools

Network and blocks

get_network_status — current network status and connection information
get_block — a block by number, hash, or latest
get_latest_blocks — recent blocks; count defaults to 10 (max 100) and offset skips that many blocks back from the head
get_transaction — transaction detail by hash

Balances and fees

get_celo_balances — CELO plus the core Mento stablecoins for an address; symbols are read from each contract on chain, so they come back as USDm, EURm and BRLm
get_stable_token_balance — a wider set of tokens in one multicall: CELO, the Mento stablecoins, and USDC, USDT, USDGLO, cKES and others; symbols come from the server’s built-in token table, so the same three stablecoins are reported as cUSD, cEUR and cREAL
get_token_balance — the balance of one specific token for an address
get_gas_fee_data — current gas fees, including EIP-1559 fields

USDm, EURm and BRLm are the on-chain symbols of the Mento stablecoins, formerly cUSD, cEUR and cREAL. The two balance tools above name the same three assets differently, so match on the token address rather than the symbol when you combine their output. USDM with a capital M is a different asset from a different issuer.

Governance

get_governance_proposals — governance proposals, paginated; page_size defaults to 10 (max 20)
get_proposal_details — detail for one proposal

Staking and validators

get_staking_balances — staking balances for an address, by validator group
get_activatable_stakes — pending stakes that can be activated for rewards
get_total_staking_info — network-wide staking and participation metrics
get_validator_groups — validator groups with members, votes, capacity and performance. Paginated, page_size defaults to 10, so a single call is not the full set
get_validator_group_details — detail for one validator group

Run as a remote HTTP endpoint

Running the server over Streamable HTTP lets clients connect with a single URL and no local Python install. This is server operation — if you only want the server on your own machine, the stdio configurations above are all you need.

celo-mcp-server --transport http --host 0.0.0.0 --port 3000

MCP_TRANSPORT, HOST and PORT set the same three values from the environment.

The defaults bind 127.0.0.1 and accept only localhost hostnames. A remote client against a default-configured server fails twice over: connection refused, because nothing listens on the public interface — fix with --host 0.0.0.0 or HOST; then HTTP 421 Misdirected Request, because the DNS-rebinding check rejects the public hostname — fix by setting MCP_ALLOWED_HOSTS to that hostname.

Variable	Purpose	Default
`MCP_TRANSPORT`	`stdio` or `http`	`stdio`
`HOST` / `PORT`	HTTP bind host and port	`127.0.0.1` / `3000`
`MCP_ALLOWED_HOSTS`	Hostnames accepted by the DNS-rebinding check, comma-separated. Set to your public hostname, or `*` to disable the check	localhost only
`MCP_CORS_ORIGINS`	Allowed origins, comma-separated, or `*`	`*`
`MCP_RATE_LIMIT` / `MCP_RATE_WINDOW`	Requests per client per window in seconds. `/health` is exempt	`60` / `60`
`MCP_TRUST_PROXY`	Number of trusted `X-Forwarded-For` hops. Behind a load balancer or Cloud Run, leaving this unset makes every client share one rate-limit bucket keyed on the proxy IP	unset
`MCP_AUTH_TOKEN`	If set, `/mcp` requires `Authorization: Bearer <token>`	unset, open

GET /health returns 200 for hosting health checks. Point a remote-capable client at the URL. The type field is required — an entry with a url and no type is read as a stdio server and silently skipped:

Claude Code
VS Code
Cursor
Claude Desktop

claude mcp add --transport http celo-mcp https://<your-host>/mcp

With MCP_AUTH_TOKEN set on the server:

claude mcp add --transport http celo-mcp https://<your-host>/mcp \
  --header "Authorization: Bearer <token>"

{
  "servers": {
    "celo-mcp": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Drop headers if the server has no MCP_AUTH_TOKEN.

{
  "mcpServers": {
    "celo-mcp": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Development

git clone https://github.com/celo-org/celo-mcp
cd celo-mcp
pip install -e ".[dev]"

pytest                 # run tests
black src/             # format
ruff check src/        # lint
mypy src/              # type-check

Resources

Resource	Link
Source	celo-org/celo-mcp
Package	celo-mcp on PyPI
Deployment guide	docs/DEPLOYMENT.md
Model Context Protocol	modelcontextprotocol.io

What is MCP? - how the protocol works and which Celo servers exist
Celo Docs MCP Server - search these docs from your editor
Celina - an agent wallet, for the write side
Network information - chain IDs, RPC URLs and explorers

Overview

Build with AI

Use Cases

Fee Abstraction

What it covers

Prerequisites

Install

Connect your client

Available tools

Network and blocks

Balances and fees

Governance

Staking and validators

Run as a remote HTTP endpoint

Development

Resources

​What it covers

​Prerequisites

​Install

​Connect your client

​Available tools

​Network and blocks

​Balances and fees

​Governance

​Staking and validators

​Run as a remote HTTP endpoint

​Development

​Resources

​Related

What it covers

Prerequisites

Install

Connect your client

Available tools

Network and blocks

Balances and fees

Governance

Staking and validators

Run as a remote HTTP endpoint

Development

Resources

Related