Celina — Celo MCP Server

Celina is a third-party, open-source stack that gives an LLM read, prepare, and execute access to Celo mainnet through an SDK, an MCP server, and a REST API. This package is the Model Context Protocol server — it registers the shared @andrewkimjoseph/celina-sdk/tools catalog — the same Zod schemas and handlers that power browser wallet apps — so MCP and agent hosts stay in sync with the SDK and REST API.

Website · npm · Hosted (reads + prepare) · Celo docs

Install

npm i -g @andrewkimjoseph/celina-mcp@latest

Full setup guide (Windows paths, troubleshooting): usecelina.xyz/mcp/local.

Migration

If you still use @andrewkimjoseph/celina, update your MCP config args to @andrewkimjoseph/celina-mcp and rename the server key to celina-mcp. The old package name remains published as a wrapper through one release cycle.

Quick start

Recommended: install globally and connect over stdio — full tool catalog with execute/write when you set CELO_PRIVATE_KEY, fast startup, and keys stay on your machine.

Your MCP client (Cursor, Claude Desktop, LM Studio, etc.) runs the celina-mcp binary over stdio. Tools register from @andrewkimjoseph/celina-sdk/tools via registerSdkTools. See Local stdio (recommended) or the website install guide.

For chain reads without a local install, use the hosted Streamable HTTP endpoint at https://mcp.usecelina.xyz/mcp — see Hosted (reads + prepare).

MCP setup

Pick your client, install the package, paste the config, restart. Celina shows up as MCP tools your LLM can call.

Local stdio (recommended)

Install globally, then add Celina to your MCP config. Your client runs the celina-mcp binary over stdio. Works in any stdio client (Cursor, Claude Desktop, LM Studio, Continue, MCP Inspector). Use Node.js 20 or 22 LTS (≥ 20 supported).

Why not npx -y? Cold npx starts can exceed Claude Desktop's ~60s MCP handshake on some Windows machines. Global install + an absolute celina-mcp path avoids that.

GUI clients (Cursor, Claude Desktop) often spawn MCP servers with a minimal PATH that does not include nvm, fnm, Homebrew, or npm’s global bin. Bare "command": "celina-mcp" then fails with spawn celina-mcp ENOENT and the client reconnects in a loop. Paste the absolute path from the commands below into "command" before you first connect.

Run npm i -g @andrewkimjoseph/celina-mcp@latest
Find the binary path (copy the output into "command" in step 3):
- macOS / Linux: which celina-mcp
- Windows (cmd): where celina-mcp
- Windows (PowerShell): (Get-Command celina-mcp).Source
Open your MCP config (e.g. claude_desktop_config.json, Cursor Settings → MCP) and merge a snippet below into mcpServers
Fully quit and restart the client

macOS / Linux example:

{
  "mcpServers": {
    "celina-mcp": {
      "type": "stdio",
      "command": "/path/to/celina-mcp",
      "args": [],
      "env": {
        "CELO_PRIVATE_KEY": "0x...",
        "SELF_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Windows example (use the .cmd shim path from where / Get-Command; escape backslashes in JSON):

{
  "mcpServers": {
    "celina-mcp": {
      "type": "stdio",
      "command": "C:\\Users\\YourName\\AppData\\Roaming\\npm\\celina-mcp.cmd",
      "args": [],
      "env": {
        "CELO_PRIVATE_KEY": "0x...",
        "SELF_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Replace "command" with your which / where / Get-Command output. "command": "celina-mcp" only works if the GUI app inherits npm’s global bin — often false on macOS and Windows. If path lookup is empty, install globally first, or as a last resort use "command": "node" and "args": ["<npm root -g>/@andrewkimjoseph/celina-mcp/build/index.js"] (run npm root -g to find the path; use Windows path separators in the arg on Windows).

Keep CELO_PRIVATE_KEY and SELF_AGENT_PRIVATE_KEY out of source control — they stay on your machine. Omit both for read-only chain queries.

Private keys accept 64 hex characters with or without a 0x prefix (normalized at startup). Invalid or placeholder values like 0x... are ignored at startup so read-only tools still load; write tools return a clear config error until you fix or remove the key. Self-only setups can use SELF_AGENT_PRIVATE_KEY alone (omit CELO_PRIVATE_KEY) for governance/staking when the Self agent passes humanness.

Read telemetry: Off-chain tool usage is logged via the bundled Celina SDK to celina-stats-api. Each MCP install gets a stable device_id (~/.config/celina/install-id) so stats can distinguish hosts; wallet-scoped reads also set user_id to the public wallet address (from tool args or the CELO_PRIVATE_KEY signer). Opt out or override via createServer({ analyticsEnabled: false, analyticsDeviceId: "..." }) when embedding the server programmatically.

Claude Desktop

Use the same stdio config in claude_desktop_config.json:

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

Requires Node.js ≥ 20 (20 or 22 LTS recommended).

{
  "mcpServers": {
    "celina-mcp": {
      "type": "stdio",
      "command": "/path/to/celina-mcp",
      "args": [],
      "env": {
        "CELO_PRIVATE_KEY": "0x...",
        "SELF_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Replace "command" with your which / where / Get-Command output. Fully quit and relaunch Claude Desktop after editing the config (closing the window is not enough).

Local stdio (from source)

For development from a cloned repo, point at your local build/index.js:

{
  "mcpServers": {
    "celina-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/celina-mcp/build/index.js"],
      "env": {
        "CELO_PRIVATE_KEY": "0x...",
        "SELF_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Run Celina with your own model

Celina is a plain MCP server. Pair it with any MCP-aware local stack — Ollama, LM Studio, llama.cpp — through a client that supports tool calling.

Read-only tools (balances, blocks, GoodDollar status, etc.) work out of the box. For write tools, set CELO_PRIVATE_KEY in the MCP server env block. Stdio writes simulate each prepared step before broadcast to catch reverts before gas is spent.

LM Studio (0.3.17+)

Native MCP hosting via mcp.json.

Program → Install → Edit mcp.json
Add Celina under mcpServers
Enable Allow calling servers from mcp.json
Chat with a tool-capable model (Qwen 2.5, Llama 3.1+)

{
  "mcpServers": {
    "celina-mcp": {
      "type": "stdio",
      "command": "/path/to/celina-mcp",
      "args": [],
      "env": {
        "CELO_PRIVATE_KEY": "0x...",
        "SELF_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Replace "command" with your which / where / Get-Command output. Omit CELO_PRIVATE_KEY for read-only.

Continue · VS Code

Agent mode in your editor. Drop a YAML file into your workspace and Continue picks it up in agent mode.

Create .continue/mcpServers/celina-mcp.yaml
Paste the snippet below
Switch Continue to agent mode and prompt

name: Celina
version: 0.0.1
schema: v1
mcpServers:
  - name: celina-mcp
    type: stdio
    command: /path/to/celina-mcp
    args: []

Replace command with your which / where / Get-Command output.

Alternatively, copy the local stdio JSON into .continue/mcpServers/mcp.json — Continue picks up Claude/Cursor-style configs automatically.

Test without an LLM

Use MCP Inspector to call Celina tools directly over stdio:

npm run build
npm run inspect

Tips

Use models with reliable tool-calling support; small or older models may skip tools or call them incorrectly.
Start with read-only prompts, e.g. "What's the USDm balance of 0x…?", "Is this wallet GoodDollar whitelisted?", or "Can this address claim GoodDollar UBI today?"
Keep private keys in env vars only — never commit them to config files in git.

Hosted (reads + prepare)

A public hosted endpoint is available at https://mcp.usecelina.xyz/mcp. Use this when you need chain reads without a local install.

Local stdio remains the recommended setup — it supports write tools with your own keys, Self Agent ID flows, and avoids serverless cold starts.

Client config (hosted, no local install):

{
  "mcpServers": {
    "celina-mcp": {
      "url": "https://mcp.usecelina.xyz/mcp"
    }
  }
}

The hosted service runs on Cloudflare Workers via celina-mcp-remote. Do not send private keys to the hosted endpoint — writes are disabled server-side.

Works without keys: all hosted get_* reads — including check_humanness, governance reads (get_governance_proposals, get_queued_proposals, get_actionable_governance_proposals, get_locked_celo_balance, get_pending_withdrawals, get_votable_proposals, get_governance_votes), staking reads (get_stake_eligibility, get_delegation_info, get_governance_delegates, get_governance_delegate_details), get_celo_account_registration, get_gooddollar_identity_link, Aave/GoodDollar quotes, Self verify/lookup, AgentKarma, NFT/contract reads, etc.

Hosted MCP: 50 tools — reads, oracle/AMM quotes, swap pair lists, attribution check/verify, humanness check, governance/staking reads, and AgentKarma reputation (read-only external API; explicit address required — no signer fallback). estimate_*, server-key writes (send_token, execute_lock_celo, execute_stake, execute_gooddollar_reserve_swap, etc.), get_wallet_address, GoodDollar connect/disconnect/claim writes, and Self lifecycle/registration tools require local stdio with CELO_PRIVATE_KEY / SELF_AGENT_PRIVATE_KEY.

Unreliable on serverless: register_self_agent / check_self_registration — Self sessions are in-memory and do not persist across stateless function invocations.

See celina-mcp-remote/README.md if you want to deploy your own instance.

Write tools

Set CELO_PRIVATE_KEY and/or SELF_AGENT_PRIVATE_KEY in your MCP server env block for on-chain writes. Pass optional signer: "celo" | "self_agent" when both keys are configured. Stdio writes include: send_token, DeFi executes (execute_mento_fx, execute_uniswap_swap, execute_gooddollar_reserve_swap, supply_aave, withdraw_aave), governance (execute_lock_celo, execute_vote, execute_upvote, …), staking (execute_stake, execute_activate_stake, …), execute_register_celo_account, GoodDollar UBI/identity writes, and execute_contract_function. Humanness-gated governance/staking executes require check_humanness to pass first. Keys stay on your machine and are not sent to Celina's authors.

Session wallet (local stdio)

When a signing key is configured, the server derives session wallet(s) at startup. Agents should use them like this:

get_wallet_address — with no signer, returns the default address plus wallets.celo and wallets.self_agent when both keys are set; pass signer to look up one wallet.
Default signer: celo when CELO_PRIVATE_KEY is set (even if Self key is also set); self_agent when only SELF_AGENT_PRIVATE_KEY is configured.
Omit address / wallet_address / from on wallet-scoped reads for “my” balances and activity (uses default signer).
Pass signer: "celo" | "self_agent" on execute tools (send, governance, staking, account register, GoodDollar connect/disconnect) to choose which configured wallet acts.
Never derive addresses from shell or read .env.

Wallet-scoped tools with optional address: get_account, token balance tools, staking/governance reads, GoodDollar reads, get_nft_balance, estimate_transaction (from only), contract reads (fromAddress).

On hosted MCP (no key), pass explicit addresses. get_wallet_address is omitted from the hosted tool list.

Browser apps using @andrewkimjoseph/celina-sdk filter the same tool catalog with surface: "browser" and pass the user’s connected wallet on each call — see tool catalog guide and MCP session wallet guide.

Environment variables

Variable	Default	Description
`CELO_PRIVATE_KEY`	—	Main wallet for writes (send, DeFi, governance, staking, GoodDollar UBI). 64 hex chars, optional `0x` prefix.
`SELF_AGENT_PRIVATE_KEY`	—	Self Agent ID wallet (separate from CELO). Can be used alone for humanness-gated governance/staking. Optional `0x` prefix.
`SELF_AGENT_API_BASE`	`https://app.ai.self.xyz`	Override Self Agent ID REST API base URL
`CELO_RPC_URL_MAINNET`	Forno public RPC	Override mainnet RPC
`ETH_RPC_URL_MAINNET`	—	Ethereum RPC for ENS resolution

Account Abstraction / gas sponsorship: Celina MCP does not take a Pimlico (or other) sponsorship API key. Sponsored UserOps use @andrewkimjoseph/celina-sdk createAAClient in your app with your gasSponsorship provider credentials. Stdio execute_* remains EOA-only via CELO_PRIVATE_KEY.

Copy .env.example to .env for local development.

Known tokens

All supported tokens live in the celina-sdk token registry:

Category	Symbols
Native	`CELO`
Mento stablecoins	`USDm`, `EURm`, `BRLm`, `XOFm`, `KESm`, `PHPm`, `COPm`, `GBPm`, `CADm`, `AUDm`, `ZARm`, `GHSm`, `NGNm`, `JPYm`, `CHFm`
Bridged / third-party	`USDT`, `USDC`, `USAT`, `vEUR`, `vGBP`, `vCHF`, `USDM`, `USDA`, `EURA`, `USDGLO`, `BRLA`, `COPM`
GoodDollar	`GoodDollar`, `G$` (`0x62B8B11039FcfE5aB0C56E502b1C372A3d2a9c7A`)

Token symbols are resolved case-insensitively. Mento legacy tickers (cUSD, cEUR, cKES, PUSO, cREAL, eXOF, etc.) map to the current XXXm names. You can also pass a known registry contract address.

get_celo_balances — named registry tokens (defaults to CELO + USDm)
get_stablecoin_balances — scan all registry stablecoins in one call (omits zero balances by default)

Tools

Full schemas and handlers live in @andrewkimjoseph/celina-sdk/tools. MCP registers them via registerSdkTools — no per-tool files in this repo.

Core

Tools	Notes
`get_network_status`, `get_block`, `get_latest_blocks`, `get_transaction`	Chain reads
`check_attribution_tag`, `verify_attribution_tag`	ERC-8021 attribution on txs
`get_wallet_address`	Stdio only — default + dual-wallet addresses
`get_account`, `get_celo_account_registration`, `execute_register_celo_account`	Account balance, nonce, Celo Accounts registration
`resolve_ens`	Celo + Ethereum ENS

Tokens and DeFi

Tools	Notes
`get_celo_balances`, `get_stablecoin_balances`, `get_token_info`, `get_token_balance`	Registry token reads
`get_gas_fee_data`, `estimate_transaction`, `estimate_send`, `send_token`	Sends (stdio writes)
`get_mento_swap_pairs`, `get_mento_fx_quote`, `estimate_mento_fx`, `execute_mento_fx`	Mento FX
`get_uniswap_swap_pairs`, `get_uniswap_quote`, `estimate_uniswap_swap`, `execute_uniswap_swap`	Uniswap v4
`get_aave_balances`, `supply_aave`, `withdraw_aave`	Aave V3 Celo
`get_gooddollar_*`, `claim_daily_gooddollar_ubi`, `execute_gooddollar_reserve_swap`, `get_gooddollar_face_verification_link`, `execute_connect_gooddollar_identity`, `execute_disconnect_gooddollar_identity`	GoodDollar identity, UBI, reserve — see GoodDollar

Governance (humanness-gated writes)

Reads	Stdio executes
`get_governance_proposals`, `get_proposal_details`, `get_queued_proposals`, `get_actionable_governance_proposals`, `get_votable_proposals`, `get_governance_votes`, `get_locked_celo_balance`, `get_pending_withdrawals`	`execute_lock_celo`, `execute_unlock_celo`, `execute_relock_celo`, `execute_withdraw_celo`, `execute_vote`, `execute_upvote`, `execute_dequeue_proposals_if_ready`, `execute_revoke_governance_votes`, `execute_revoke_governance_upvote`

Discover: get_queued_proposals (Queue), get_votable_proposals (Referendum), or get_actionable_governance_proposals (both). Optional: get_proposal_details(proposal_id) for CGP title and markdown before acting. When dequeueReady, call execute_dequeue_proposals_if_ready before upvoting proposals with upvoteable=false. Queue flow: get_queued_proposals → execute_upvote (or dequeue first if overdue). Referendum flow: get_votable_proposals → execute_vote. Call check_humanness before humanness-gated executes (dequeue is not humanness-gated).

Staking (humanness-gated writes)

Reads	Stdio executes
`get_staking_balances`, `get_activatable_stakes`, `get_validator_groups`, `get_validator_group_details`, `get_total_staking_info`, `get_delegation_info`, `get_governance_delegates`, `get_governance_delegate_details`, `get_stake_eligibility`	`execute_stake`, `execute_activate_stake`, `execute_unstake`, `execute_delegate_power`, `execute_undelegate_power`

Call get_stake_eligibility before execute_stake — groups at capacity (e.g. cLabs) will fail.

Governance delegation discovery

When the user asks who to delegate to: get_governance_delegates → pick a delegatee address → get_governance_delegate_details (optional profile lookup) → get_delegation_info + get_locked_celo_balance → execute_delegate_power. When they already have an address: start with get_governance_delegate_details. The Celo Mondo directory is curated off-chain (not an on-chain registry); any address can receive delegation.

Humanness

Tool	Notes
`check_humanness`	Passes if Self Agent ID or GoodDollar whitelist succeeds for the address; gates governance/staking executes

NFT and contract

Tools	Notes
`get_nft_info`, `get_nft_balance`	ERC-721 / ERC-1155
`call_contract_function`, `estimate_contract_gas`, `execute_contract_function`	Caller-supplied ABI

Self Agent ID

Reads	Stdio session / signing
`verify_self_agent`, `lookup_self_agent`, `verify_self_request`	`register_self_agent`, `check_self_registration`, `refresh_self_proof`, `deregister_self_agent`, `get_self_identity`, `sign_self_request`, `authenticated_self_fetch`

See Self Agent ID notes below.

AgentKarma

Tools	Notes
`get_agentkarma_reputation`, `get_agentkarma_celo_agent`, `check_agentkarma_counterparty`	Read-only external API; hosted requires explicit `address`

Swap routing (Mento FX, GoodDollar reserve, Uniswap v4)

Three swap routes are available. Pick based on the token pair. Call get_mento_swap_pairs / get_uniswap_swap_pairs when the pair is unknown — do not invent pairs.

Route	Best for	Quote tool	Execute (MCP)
Mento FX	Mento oracle stables (USDm, EURm, CELO, …)	`get_mento_swap_pairs` then `get_mento_fx_quote`	`estimate_mento_fx` → `execute_mento_fx`
GoodDollar reserve	G$ ↔ USDm (bonding curve)	`get_gooddollar_reserve_quote`	`estimate_gooddollar_reserve_swap` → `execute_gooddollar_reserve_swap`
Uniswap v4	AMM pairs (e.g. G$ → USDT, USDC → USDT)	`get_uniswap_swap_pairs` then `get_uniswap_quote`	`estimate_uniswap_swap` → `execute_uniswap_swap`

G$ ↔ USDm uses the GoodDollar reserve — not Uniswap (pools are typically illiquid). G$ → USDT and similar AMM pairs use Uniswap when Mento FX has no route. CELO swaps on Uniswap route through WCELO pools — the signer needs WCELO (wrapped CELO) balance, not native CELO. All on-chain steps include Celina ERC-8021 Schema 0 attribution (celina + optional app codes). Prefer check_attribution_tag to confirm tx tags on a tx hash. Sponsored UserOps use the SDK createAAClient in your app — Celina MCP does not host Pimlico/gas sponsorship keys.

Recommended LLM flow: quote the relevant route(s), compare expectedOut, then estimate and execute on the better route (or use SDK prepareReserveSwap / prepare_swap for user wallet signing on reserve swaps).

GoodDollar

UBI

Daily G$ claims via UBISchemeV2 on Celo (0x43d72Ff17701B2DA814620735C39C620Ce0ea4A1). Identity must be whitelisted; connected wallets resolve to their verified root. Balance and reserve tools use the literal wallet address only. One claim per identity per UBI period.

Tool	Type	Notes
`get_gooddollar_identity_link`	read	Root vs connected-wallet link
`get_gooddollar_whitelisting_info`	read	IdentityV4 status, reverification timeline (root-resolved)
`get_gooddollar_ubi_entitlement`	read	Claimable G$, whitelist root, eligibility reasons
`claim_daily_gooddollar_ubi`	write	Claims for MCP server wallet (`CELO_PRIVATE_KEY`); stdio only

Recommended flow: get_gooddollar_ubi_entitlement → claim_daily_gooddollar_ubi (or use SDK prepareClaimUbi + wagmi for user wallet signing).

Reserve swaps (G$ ↔ USDm)

On-chain MentoBroker bonding curve — the canonical route for GoodDollar ↔ USDm. MCP can quote, estimate, and execute on stdio with CELO_PRIVATE_KEY. Browser apps use prepare_gooddollar_reserve_swap or prepare_swap.

Tool	Type	Notes
`get_gooddollar_reserve_quote`	read	Hosted + stdio; pair-limited to G$ ↔ USDm
`estimate_gooddollar_reserve_swap`	read*	Gas estimate (*needs `CELO_PRIVATE_KEY`)
`execute_gooddollar_reserve_swap`	write	Stdio only; signs approve + broker `swapIn`

Details: celina-sdk GoodDollar guide.

Self Agent ID notes

Registration lifecycle APIs (register_self_agent, refresh_self_proof, deregister_self_agent) use network: "mainnet" in the Self REST API request body.
Demo and gated HTTP endpoints (e.g. https://app.ai.self.xyz/api/demo/verify) require the query param network=celo-mainnet, not network=mainnet.
QR scan URLs use /scan/{sessionToken}, not /qr/....
refresh_self_proof only starts after on-chain proof expiry (isProofFresh is false); while fresh it returns a clear error instead of a QR that will fail on-chain. The 30-day is_expiring_soon flag (matching Self SDK isProofExpiringSoon) is for warnings only. Self SDK also documents deregister → re-register as an alternative renewal path.

Example authenticated demo call:

authenticated_self_fetch
  method: POST
  url: https://app.ai.self.xyz/api/demo/verify?network=celo-mainnet
  body: {}

Adding a new tool

Add a ToolDefinition in celina-sdk src/tools/domains/ and export it from ALL_TOOL_DEFINITIONS (see @andrewkimjoseph/celina-sdk/tools).
MCP picks it up automatically via registerSdkTools in src/tools/sdk-register.ts — no per-tool MCP file required.
Add domain logic in celina-sdk services if the handler needs new client methods.
Rebuild both packages: npm run build in celina-sdk, then celina-mcp.

Set surfaces on the definition ("mcp", "browser", or both) and use filterToolDefinitions options (serverKeyToolsEnabled, estimateToolsEnabled) to control hosted vs stdio exposure.

For developers

Architecture split

Chain logic comes from @andrewkimjoseph/celina-sdk via src/context/app-context.ts. Write tools call SDK prepare* methods, then executePreparedFlow simulates each step with simulatePreparedStep before signing:

Layer	Source	Examples
Reads	celina-sdk	balances, blocks, quotes, governance/staking reads, GoodDollar, ENS, humanness
DeFi writes	SDK `prepare*` + local executor	`send_token`, Mento/Uniswap/reserve/Aave executes
Governance / staking writes	`governanceWrite`, `stakingWrite`	`execute_lock_celo`, `execute_stake`, … (humanness-gated)
Account / GoodDollar identity	`accountWrite`, `gooddollarIdentityWrite`, `gooddollarFaceVerification`	`execute_register_celo_account`, connect/disconnect, face verification link
Self Agent ID	celina-sdk `client.self`	registration, proof refresh, authenticated fetch (`SELF_AGENT_PRIVATE_KEY`)

Before each wallet.sendTransaction, executePreparedFlow calls simulatePreparedStep from @andrewkimjoseph/celina-sdk/simulation. Reverts are caught before gas is spent; a post-mine receipt.status check remains as a safety net. No feeCurrency — the server wallet pays CELO gas.

Mento FX routing uses @mento-protocol/mento-sdk transitively through celina-sdk — MCP does not import it directly.

Self Agent ID is implemented in @andrewkimjoseph/celina-sdk (client.self). For browser-first Self UIs, also see @selfxyz/agent-sdk.

Directory map

Path	Purpose
`src/index.ts`	stdio MCP bootstrap — loads env, connects transport
`src/server/`	`createServer()` factory and LLM instructions
`src/context/`	Composes SDK client + MCP runtime (wallet, executors, hooks)
`src/tools/`	`registerSdkTools` — registers filtered `ALL_TOOL_DEFINITIONS` from celina-sdk
`src/services/`	Wallet executor (`execute-prepared-flow.ts`) for signed broadcasts
`src/config/`	Env, token registry, Self constants

Tool schemas, descriptions, and handlers live in celina-sdk src/tools/domains/. MCP only wires them to @modelcontextprotocol/sdk — see Adding a new tool.

Local development

npm run dev          # watch TypeScript → build/
npm run inspect      # MCP Inspector UI over stdio

Point your MCP client at the built entry for source development:

"args": ["/absolute/path/to/celina-mcp/build/index.js"]

Copy .env.example to .env for CELO_PRIVATE_KEY, SELF_AGENT_PRIVATE_KEY, and RPC overrides.

Troubleshooting

Symptom	Likely cause	What to do
MCP disconnects after ~60s; logs show `notifications/cancelled`	Cold `npx -y` or slow first import exceeds Claude Desktop handshake timeout	`npm i -g @andrewkimjoseph/celina-mcp@latest`; set `"command"` to absolute path from `which` / `where` / `Get-Command`; Node 20/22 LTS — see usecelina.xyz/mcp/local
Cursor reconnect loop; logs show `spawn celina-mcp ENOENT`	GUI PATH missing npm’s global bin (nvm/fnm/Homebrew on macOS; npm global prefix on Windows), or binary not installed	Run `which` / `where` / `Get-Command` (see Local stdio) and paste that absolute path into `"command"`. If lookup is empty, install globally first, or as a last resort use `"command": "node"` and `"args": ["<npm root -g>/@andrewkimjoseph/celina-mcp/build/index.js"]`
`Cannot find package 'ox'` from `permissionless` on MCP start	npm hoisted `permissionless` without `ox` at the same level	Run `npm i -g ox`, or upgrade to `@andrewkimjoseph/celina-mcp@0.18.7`+ with `@andrewkimjoseph/celina-sdk@0.25.0`+
`ERESOLVE overriding peer dependency` for `permissionless` / `ox` on install	`permissionless@0.2.57` optional peer wants `ox@^0.8.0`; Celina pins `ox@^0.10.0`	Safe to ignore on 0.18.11+; or `npm i -g @andrewkimjoseph/celina-mcp --legacy-peer-deps`; if you have `~/package.json`, add `legacy-peer-deps=true` to `~/.npmrc`
MCP server never connects / Shared MCP process crash on start	Stale npx cache, wrong command, or GUI PATH miss	Set `"command"` to absolute path from `which` / `where` / `Get-Command`; fully quit and restart your MCP client; for dev, point `args` at your local `build/index.js`
`EPIPE: broken pipe` in logs	Client closed stdio before late `initialize` response	Fix slow startup (global install + `celina-mcp` command)
Write tools fail immediately	Invalid or placeholder `CELO_PRIVATE_KEY` / `SELF_AGENT_PRIVATE_KEY`	Use 64 hex chars (with or without `0x`); remove placeholder values like `0x...`. Invalid keys no longer block startup — fix the env value and restart for writes

Roadmap

Mento FX routing (get_mento_swap_pairs, get_mento_fx_quote, estimate_mento_fx, execute_mento_fx)
Uniswap v4 swaps (get_uniswap_swap_pairs, get_uniswap_quote, estimate_uniswap_swap, execute_uniswap_swap)
Aave tools (get_aave_balances, supply_aave, withdraw_aave) — USDT, WETH, USDm, USDC, CELO, EURm
Self proof verification (verify_self_agent, verify_self_request, ai.self.xyz)
Self Agent ID check (lookup_self_agent, registration & lifecycle tools)
Governance executes (execute_lock_celo, execute_vote, execute_upvote, …)
Staking executes (execute_stake, execute_activate_stake, delegate/undelegate)
Governance delegate discovery (get_governance_delegates, get_governance_delegate_details — Celo Mondo directory)
Humanness gate (check_humanness) and GoodDollar identity connect/disconnect

License

MIT

Name		Name	Last commit message	Last commit date
assets		assets
bin		bin
scripts		scripts
src		src
tests		tests
wrapper		wrapper
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.unit.config.ts		vitest.unit.config.ts

Latest commit

History

Folders and files

Repository files navigation