Skip to main content
Glama
crypto-mcp-server

crypto-mcp-server

by akshaygp18

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

Tool

Purpose

check_api_status

Upstream health plus this server's config and cache stats

list_supported_currencies

Every accepted vs_currency code

search_coins

Resolve a name or symbol to a CoinGecko coin id

get_coin_price

Spot prices for many coins in many currencies at once

convert_crypto_amount

Convert a quantity of a coin into another currency

get_coin_details

Full profile: supply, ATH, 24h/7d/30d changes

list_top_coins

Ranked market table by market cap, volume, or id

get_market_chart

Historical price / market cap / volume series

get_ohlc_candles

Candlestick data

get_historical_price

Market state on one past date (needs a paid plan)

get_trending_coins

Most-searched coins of the last 24 hours

get_global_market_overview

Total market cap, volume, BTC/ETH dominance

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.

Variable

Default

Meaning

CRYPTO_MCP_API_KEY

(unset)

CoinGecko Demo or Pro key

CRYPTO_MCP_API_TIER

inferred

public, demo, or pro

CRYPTO_MCP_BASE_URL

follows tier

API root; override for a proxy or mock

CRYPTO_MCP_TIMEOUT_SECONDS

15.0

Total request timeout

CRYPTO_MCP_CONNECT_TIMEOUT_SECONDS

5.0

Connect timeout

CRYPTO_MCP_MAX_RETRIES

3

Retries after the first attempt

CRYPTO_MCP_BACKOFF_BASE_SECONDS

0.5

First-retry backoff factor

CRYPTO_MCP_BACKOFF_MAX_SECONDS

8.0

Ceiling on any single sleep

CRYPTO_MCP_MAX_CONNECTIONS

10

Connection pool size

CRYPTO_MCP_RATE_LIMIT_PER_MINUTE

tier default

Client-side outbound ceiling

CRYPTO_MCP_CACHE_TTL_SECONDS

30.0

Response cache TTL; 0 disables

CRYPTO_MCP_CACHE_MAX_ENTRIES

512

Cache size before LRU eviction

CRYPTO_MCP_LOG_LEVEL

INFO

DEBUG…CRITICAL

CRYPTO_MCP_LOG_FORMAT

text

text or json

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.

Available Tools

12 tools
check_api_statusCheck CoinGecko API statusA
Read-only

Verify that the CoinGecko API is reachable and report this server's configuration and cache statistics. Use this first when other tools are failing, to tell an upstream outage from a configuration problem.

Inputs: no named parameters. Returns: Health of the upstream CoinGecko API and this server's local state.

convert_crypto_amountConvert a crypto amountA
Read-only

Convert a quantity of one cryptocurrency into another currency at the current rate, e.g. 2.5 ETH in USD.

Inputs: amount (required), coin_id (required), vs_currency. Returns: Value of an amount of one asset expressed in another.

get_coin_detailsGet coin detailsA
Read-only

Get a full profile for one coin: description, homepage, categories, supply figures, all-time high, and current market data including 24h, 7d, and 30d price changes.

Inputs: coin_id (required), vs_currency. Returns: Profile and current market state for one coin.

get_coin_priceGet current coin pricesA
Read-only

Get current prices for one or more coins in one or more currencies, optionally with market cap, 24-hour volume, and 24-hour change. Batch coins into a single call rather than calling once per coin.

Inputs: coin_ids (required), vs_currencies, include_24h_change, include_24h_volume, +1 more. Returns: Result of a multi-coin, multi-currency price lookup.

get_global_market_overviewGet global market overviewA
Read-only

Get aggregate statistics for the whole crypto market: total market cap, total 24-hour volume, BTC and ETH dominance, and the number of tracked coins and markets.

Inputs: vs_currency. Returns: Aggregate statistics for the whole cryptocurrency market.

get_historical_priceGet price on a past dateA
Read-only

Get a coin's price, market cap, and volume as of 00:00 UTC on a past calendar date. For a range of dates use get_market_chart instead. Note: CoinGecko restricts this endpoint to Demo and Pro plans — without an API key it fails. get_market_chart covers history on the public tier.

Inputs: date (required), coin_id (required), vs_currency. Returns: Market state for one coin on one past calendar day (00:00 UTC).

get_market_chartGet historical market chartA
Read-only

Get historical price, market cap, and volume series for a coin over a look-back window. Long windows are down-sampled to max_points evenly spaced observations; the reported change_percent is always computed from the full series.

Inputs: coin_id (required), days, interval, max_points, +1 more. Returns: Historical price, market cap, and volume for one coin. Series are down-sampled…

get_ohlc_candlesGet OHLC candlestick dataA
Read-only

Get open/high/low/close candles for a coin. CoinGecko picks the candle width from the window: 30 minutes up to 2 days, 4 hours up to 30 days, 4 days beyond that. The chosen width is reported in the result.

Inputs: coin_id (required), days, vs_currency. Returns: Candlestick series for one coin.

list_supported_currenciesList supported quote currenciesA
Read-only

List every currency code accepted as a vs_currency by the other tools, including fiat ('usd', 'eur') and crypto ('btc', 'eth').

Inputs: no named parameters. Returns: Currency codes accepted anywhere a ``vs_currency`` is required.

list_top_coinsList top coins by market capA
Read-only

List coins ranked by market cap, volume, or id, with price and 24-hour change for each. Use this for market overviews and 'top N' questions.

Inputs: page, limit, order, vs_currency. Returns: A page of the ranked market table.

search_coinsSearch for coinsA
Read-only

Find coins by name or ticker symbol and return their CoinGecko ids. Call this whenever you are unsure of a coin id — every other tool expects the id slug ('bitcoin'), not the symbol ('BTC').

Inputs: query (required), limit. Returns: Coins matching a free-text query, best match first.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: price, details, history, market overview, search, conversion, health check, etc. Even similar tools like get_historical_price and get_market_chart differ by single-date vs series, and get_trending_coins vs list_top_coins differ by metric. No two tools could be easily confused.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_, get_, search_, convert_, check_). There is no mixing of camelCase or inconsistent verb styles, making the API predictable and easy to navigate.

    Tool Count5/5

    12 tools is well within the ideal 3-15 range. The server is scoped to cryptocurrency market data, and each tool serves a clear purpose without unnecessary bloat or missing essential operations.

    Completeness5/5

    The tool surface comprehensively covers the domain: real-time prices, historical data, OHLC, conversion, market rankings, global stats, coin discovery, and API diagnostics. There are no obvious gaps or dead ends; the historical price limitation is an external API restriction, not a missing tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Your agent needs crypto prices it can rely on — spot, ranked market tables, history, OHLC, per-venue tickers, and what is trending right now. **What you can ask for** • "What is the price of these 20 tokens in USD and EUR right now?" • "Give me the top 100 by market cap with 24h and 7d change." • "Chart this coin's price over the last year, hourly." • "Where does this token trade, and at what spread per venue?" • "What is trending on CoinGecko today?" **How to use it** Point any MCP client at https://mcp.aisa.one/crypto-market-data/mcp and sign in with OAuth — there is no key to create or paste. 21 CoinGecko tools: simple price and token price by contract, supported currencies, coin list and detail, ranked markets, history, market charts and ranges, OHLC, per-coin tickers, categories, exchanges and their tickers, token data and charts, and trending. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Price the token here, then ask the same agent what X is posting about it — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/finance/mcp for equities, crypto and prediction markets in one place.

    • MCP server with quote and live cryptocurrency price tools, local and cloud-deployed transports.

    • Unlock the power of real-time cryptocurrency data with our Crypto Price Insights MCP server.

    • Unofficial CoinGecko MCP — wraps CoinGecko free API (no auth required)

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      An MCP server for CoinGecko that connects any MCP-compatible client to free crypto market data, providing tools for prices, market caps, trending coins, historical data, and global stats.
      8
      52 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server providing market data for 15,000+ cryptocurrencies including prices, history, trends, and deep coin metadata via CoinGecko.
      130 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      A Model Context Protocol server for real-time cryptocurrency price data, market data, trending coins, historical charts, and currency conversion using the free CoinGecko API.
      MIT