crypto-mcp-server

An MCP server exposing live cryptocurrency market data from the CoinGecko v3 API as 12 typed tools.

Built on the MCP Python SDK 2.x (MCPServer), fully asynchronous, with a shared connection pool, client-side rate limiting, response caching, bounded retries, and structured logging.

Tools

Every tool is read-only, returns a typed model (so clients get an outputSchema), and pairs raw numerics with preformatted *_display strings — models quote the display string and compute on the raw value.

Related MCP server: CoinGecko MCP Server

Install

uv sync

Run

# stdio (default) — how MCP clients launch it
uv run crypto-mcp-server

# HTTP, for remote clients or debugging
uv run crypto-mcp-server --transport streamable-http --port 8000

# verbose, machine-readable logs
uv run crypto-mcp-server --log-level DEBUG --log-format json

python -m crypto_mcp_server works identically.

Client configuration

{
  "mcpServers": {
    "crypto": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/crypto_mcp_server", "crypto-mcp-server"],
      "env": { "CRYPTO_MCP_API_KEY": "CG-xxxxxxxxxxxx" }
    }
  }
}

Configuration

All settings come from CRYPTO_MCP_* environment variables and are resolved once at startup by Settings.from_env(). Everything is optional — the server runs anonymously against CoinGecko's public tier out of the box.

The tier is inferred from the key's presence, and the base URL follows the tier, so a Pro user only sets CRYPTO_MCP_API_KEY and CRYPTO_MCP_API_TIER=pro.

A note on rate limits

The anonymous tier is throttled per source IP and shared with every other unauthenticated caller behind it. The default client-side budgets (5/min public, 25/min demo, 450/min pro) sit deliberately below CoinGecko's published ceilings — measured against the live API, even 10/min drew constant 429s without a key. For anything beyond casual use, set an API key.

Architecture

server.py     MCP tools: argument validation, error translation, lifespan
  ↓
mappers.py    raw CoinGecko JSON → typed models
  ↓
client.py     the only module that knows HTTP
  ↓
utils.py      retry, rate limiting, TTL cache, formatting, input hygiene

config.py, exceptions.py, logging_config.py, and models.py are shared by every layer. A single request flows through:

get_json()
  └─ TTLCache.get_or_load     de-duplicates concurrent identical calls
       └─ retry_async         exponential backoff with full jitter
            └─ AsyncRateLimiter
                 └─ httpx2    one attempt

Caching sits outside retries so a retried call is stored once; the limiter sits inside them so every physical attempt is metered.

Error handling

Failures are expressed as a shallow hierarchy under CryptoMCPError (ToolInputError, RateLimitError, AuthenticationError, ResourceNotFoundError, UpstreamTimeoutError, …). Each tool is wrapped by @tool_handler, which guarantees three things:

• Argument mistakes fail before any network call, with a message naming a valid value (order must be one of market_cap_desc, …).

• Known failures surface as ToolError with their message intact.

• Anything unexpected is logged with a full traceback and returned as a generic message — no traceback ever reaches the client.

Retries cover timeouts, connection errors, and 5xx/429 responses. When CoinGecko supplies a Retry-After longer than BACKOFF_MAX_SECONDS, the server stops rather than retrying: sleeping less than the server demanded only earns another rejection, and honouring a 60-second window inside a tool call would stall the session.

Logging

Logs go to stderr, never stdout — under the stdio transport, stdout is the JSON-RPC channel, and a stray write there corrupts the frame the client is parsing and drops the session. configure_logging also detaches any stdout handler it finds on the root logger.

Tests

uv run pytest

109 tests, no network access: upstream behaviour is simulated with httpx2.MockTransport injected into the real client, and the tool layer is driven through a genuine in-process MCP client session, so retries, caching, rate limiting, error mapping, and the wire protocol all run as they do in production.