crypto-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@crypto-mcp-server what's the current price of bitcoin?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Upstream health plus this server's config and cache stats |
| Every accepted |
| Resolve a name or symbol to a CoinGecko coin id |
| Spot prices for many coins in many currencies at once |
| Convert a quantity of a coin into another currency |
| Full profile: supply, ATH, 24h/7d/30d changes |
| Ranked market table by market cap, volume, or id |
| Historical price / market cap / volume series |
| Candlestick data |
| Market state on one past date (needs a paid plan) |
| Most-searched coins of the last 24 hours |
| 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 syncRun
# 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 jsonpython -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 |
| (unset) | CoinGecko Demo or Pro key |
| inferred |
|
| follows tier | API root; override for a proxy or mock |
|
| Total request timeout |
|
| Connect timeout |
|
| Retries after the first attempt |
|
| First-retry backoff factor |
|
| Ceiling on any single sleep |
|
| Connection pool size |
| tier default | Client-side outbound ceiling |
|
| Response cache TTL; |
|
| Cache size before LRU eviction |
|
|
|
|
|
|
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 hygieneconfig.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 attemptCaching 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
ToolErrorwith 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 pytest109 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 toolscheck_api_statusCheck CoinGecko API statusARead-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 amountARead-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 detailsARead-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 pricesARead-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 overviewARead-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 dateARead-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 chartARead-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 dataARead-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.
get_trending_coinsGet trending coinsARead-only
List the coins most searched on CoinGecko in the last 24 hours. Reflects attention, not price performance.
Inputs: no named parameters. Returns: The current trending-search leaderboard.
list_supported_currenciesList supported quote currenciesARead-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 capARead-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 coinsARead-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
Scored across 12 tools
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.
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.
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.
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
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
- AlicenseAqualityFmaintenanceAn 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.852 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server providing market data for 15,000+ cryptocurrencies including prices, history, trends, and deep coin metadata via CoinGecko.130 npm1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceA 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
- FlicenseAqualityDmaintenanceAn MCP server that enables AI agents to fetch real-time cryptocurrency prices and market data using the CoinGecko API.13-