@cyanheads/coingecko-mcp-server
v0.2.0
Published
Market data for 15,000+ cryptocurrencies — prices, history, trends, and deep coin metadata via CoinGecko.
Maintainers
Readme
Overview
Cryptocurrency market data from CoinGecko — prices, rankings, historical charts, and deep coin profiles across 15,000+ coins. Resolve a name or ticker to CoinGecko's slug-keyed ID, then chain into price lookups, ranked markets, and trend charts. Runs as a stdio process or a local Streamable HTTP server.
Tools
| Tool | Description |
|:---|:---|
| coingecko_search_coins | Resolve a coin name or ticker symbol to a CoinGecko ID (slug). The required first step before any ID-keyed tool. |
| coingecko_get_prices | Current prices and core market stats across coin/currency batches. Accepts 500 raw IDs, processes 250 unique slugs, and discloses skipped IDs and partial misses. |
| coingecko_list_markets | Ranked market table — coins by market cap, volume, or ID, optionally filtered to a category or selected IDs. |
| coingecko_get_coin | Deep single-coin profile — description, links, market data, developer activity, community, sentiment. sections trims the large record. |
| coingecko_get_market_chart | Historical price, market cap, and volume series. recent (last N days, auto-granularity) or range (explicit Unix-second window) mode. |
| coingecko_get_trending | Coins trending on CoinGecko in the last 24 hours, by search volume. |
| coingecko_get_global | Global crypto market snapshot — total market cap and volume, BTC/ETH dominance, active counts, ongoing ICOs, 24h change. |
| coingecko_list_categories | Coin categories (category_id + display name) — the valid slugs for coingecko_list_markets's category filter. |
Resources
| Resource | Description |
|:---|:---|
| coingecko://coin/{id} | Deep coin record by slug — same data as coingecko_get_coin (full record, USD market figures). |
| coingecko://global | Global crypto market snapshot — same data as coingecko_get_global. |
All resource data is also reachable via tools — the resources mirror coingecko_get_coin and coingecko_get_global exactly, so tool-only clients lose nothing. Large collections (markets, categories) are not exposed as resources; use coingecko_list_markets and coingecko_list_categories instead.
Prompts
| Prompt | Description |
|:---|:---|
| coingecko_coin_research | Guides a full single-coin research pass through the search → get_coin → get_market_chart → get_global chain. |
Capability reference
coingecko_search_coins tool
- Tickers are not unique (many coins share
ETH/USDC) — returns ranked candidates withid,symbol,name, andmarketCapRankto disambiguate - Returns the top 25 matches by relevance;
enrichment.truncatedplusshown/capdisclose when the list is capped - An empty result is a normal outcome, not an error —
enrichment.noticesuggests broadening the query
coingecko_get_prices tool
- Accepts up to 500 raw IDs; trims, lowercases, and deduplicates them, processes the first 250 unique slugs, and discloses remaining
skippedIdsseparately from upstream misses - IDs and currency codes are trimmed and lowercased across price, coin, chart, market, global, and coin-resource lookups; blank normalized entries are rejected
- One row per
(id, currency)that returned a price; market cap, 24h volume, and 24h change are optional per row - A wrong or unknown slug returns a silent empty response upstream rather than an error —
missinglists unresolved ids so a typo reads as "unresolved," not "nonexistent" - Currencies with no numeric quotes are disclosed via
enrichment.notice; unavailable quotes do not establish that a currency is unsupported lastUpdatedAtUnixSec, when present, is Unix seconds —coingecko_get_market_chart's point timestamps are milliseconds- Throws
all_missingonly when no requested id resolves - Throws
no_price_datawhen IDs resolve but no requested currency returns a numeric quote
coingecko_list_markets tool
- Sort by market cap, volume, or ID, ascending or descending, via
order - Optional
idsselects coins using the same 500-raw/250-unique bounds as price batches;appliedIdsandskippedIdsdisclose the selection without inferring missing IDs from one page - Optional
categoryfilter — pass acategoryIdfromcoingecko_list_categories - Choose either
idsorcategory; combining them returnsconflicting_filtersbecause CoinGecko ignores IDs when a category is supplied - Pagination via
pageandper_page(default 50, max 250 rows);enrichment.truncateddiscloses when a page fills - Per-coin fields include price, cap, volume, 1h/24h/7d change, supply, and ATH/ATL
- Empty pages explain that the current page returned no rows and suggest page 1 or revised filters
- Throws
unknown_categorywhen CoinGecko returns HTTP 404 for a category-filtered request
coingecko_get_coin tool
- Six sections —
profile,market,links,developer,community,sentiment;sectionstrims the response to just what's needed (the full record is large) - Prices and every percentage-change window use
vs_currency(defaults tousd); zero changes are preserved, null/missing metrics are omitted - Quoted records, including null price keys, need no extra request. Missing quote keys consult the supported-currency catalog only when market data is selected; supported but unquoted currencies stay sparse
- Primary and conditional currency requests, including retries and backoff, share a 50-second deadline; profile-only selections skip currency validation
profile.categoriesare display names (e.g."Layer 1 (L1)") — distinct from thecategoryIdslugscoingecko_list_categoriesreturns- Sparse upstream fields are omitted rather than fabricated
- Throws
coin_not_foundwhen the slug isn't recognized upstream - Throws
unsupported_currencyonly when the supported-currency catalog excludes the requested market currency; catalog failures remain upstream errors
coingecko_get_market_chart tool
recentmode accepts 1–365 days;"max"is an explicit alias for the 365-day keyless/Demo history window and emits a noticerangemode: an explicit window viafrom/toas Unix secondsintervalselectsauto(upstream default),daily, orhourly, subject to upstream tier/window availabilitypoint_offset(default 0) andpoint_limit(default 100, effective cap 250) return exact indexed observations from each original series; larger limits use the cap with a notice- Both response surfaces carry every returned price, market-cap, and volume point; per-series totals and
nextPointOffsetsupport continuation - Subsequent pages refetch upstream data and are not snapshots; observations can revise and recent windows can move
granularitymeasures the complete original price series as5-minute,hourly,daily,irregular, orunknown;observedIntervalInMsreports median positive timestamp spacing when measurable- Point timestamps are Unix milliseconds —
coingecko_get_prices'slastUpdatedAtUnixSecis seconds - Throws
invalid_rangeon a mode/parameter mismatch,coin_not_foundwhen the slug isn't recognized
coingecko_get_trending tool
- No parameters — 24-hour trending coins by search volume, each with
marketCapRank,priceUsd,priceBtc, andpriceChangePercentage24hUsdwhen available - Upstream reports market cap and volume as pre-formatted display strings, not numbers — those fields are omitted rather than presented as numeric data
nftCountreports the trending-NFT count upstream also returns; NFT detail itself isn't surfaced
coingecko_get_global tool
- No coin id needed — one call for the macro snapshot
vs_currency(defaultusd) scopes only total market cap and volume; dominance and the 24h change percentages are always USD-denominated upstream- Throws
unsupported_currencywhen the requested currency has no entry in upstream's per-currency maps —/globalhas no upstream currency validation, so an unknown code silently returns no totals - Returns active-cryptocurrency and active-market counts, ongoing ICO count, and a Unix-second snapshot timestamp
coingecko_list_categories tool
- Optional
name_containsfilters the complete category list locally by whitespace-separated tokens — case- and punctuation-insensitive, every token must appear in the name - Unfiltered calls preserve every category and disclose the actual catalog size with narrowing examples
enrichment.totalCountreports the total category count before any local filter- Returned
categoryIdvalues are whatcoingecko_list_markets'scategoryparam expects - A filter that matches nothing returns
enrichment.noticesuggesting an unfiltered browse instead
coingecko://coin/{id} resource
- Same data as
coingecko_get_coin's full record, always denominated in USD {id}is a CoinGecko slug (e.g."bitcoin") — resolve tickers withcoingecko_search_coins- URI escapes are decoded once before trimming and lowercasing;
%20Bitcoin%20resolves tobitcoin, while malformed escapes fail validation - Throws
coin_not_foundwhen the slug isn't recognized upstream
coingecko://global resource
- Same data as
coingecko_get_global, always denominated in USD - No parameters
coingecko_coin_research prompt
- Argument:
coinrequired — a name, ticker, or CoinGecko slug - Returns an assistant framing message plus a user message that walks the search → get_coin → get_market_chart → get_global chain
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
CoinGecko-specific:
- Type-safe client for the CoinGecko v3 REST API, with one service method per endpoint
- Runs keyless on the public tier; an optional Demo API key (
x-cg-demo-api-key) raises the rate ceiling with no other config change - Calibrated retry/backoff for rate limits, transient upstream failures, and timeouts; honors
Retry-After, while permanent refusals (including HTTP 501) fail immediately - Status-specific error reasons and recovery, with bounded plain-text explanations from CoinGecko's JSON error envelopes; historical-window restrictions recommend narrowing the range
Agent-friendly output:
- Search-before-query enforced through descriptions — every ID-keyed tool states slugs-not-tickers and points back to
coingecko_search_coins - Partial reads — price results disclose unresolved IDs and currencies without quotes; total misses and resolved coins without numeric quotes produce distinct errors. Enrichment discloses caps and applied filters
- Units made explicit — timestamp fields document seconds vs. milliseconds so callers don't misread them
- Required CoinGecko attribution ships on every tool and resource output; the research prompt instructs the agent to attribute its findings the same way
Getting started
Add the following to your MCP client configuration file. No API key is required — set COINGECKO_API_KEY only to attach the higher CoinGecko Demo tier (see Configuration).
{
"mcpServers": {
"coingecko-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/coingecko-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}Or with npx (no Bun required):
{
"mcpServers": {
"coingecko-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/coingecko-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}Or with Docker:
{
"mcpServers": {
"coingecko-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/coingecko-mcp-server:latest"
]
}
}
}To attach a CoinGecko Demo key, add "COINGECKO_API_KEY": "your-demo-key" to the env block (or -e COINGECKO_API_KEY=your-demo-key for Docker).
For Streamable HTTP, set the transport and start the server:
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcpPrerequisites
- Bun v1.4.0 or higher (or Node.js v24+).
- No account or API key required to run. Optionally, a free CoinGecko Demo API key for a higher rate ceiling (10k calls/month, 100 req/min) over the shared keyless public pool.
Installation
- Clone the repository:
git clone https://github.com/cyanheads/coingecko-mcp-server.git- Navigate into the directory:
cd coingecko-mcp-server- Install dependencies:
bun install- Configure environment (optional):
cp .env.example .env
# the server runs with no .env at all; edit only to set COINGECKO_API_KEYConfiguration
The server runs with zero configuration. The one server-specific variable is optional:
| Variable | Description | Default |
|:---|:---|:---|
| COINGECKO_API_KEY | Optional CoinGecko Demo API key. When set, it is sent as the x-cg-demo-api-key header for the dedicated Demo tier (10k/mo, 100 req/min); the base URL is unchanged. Absent → keyless public tier (shared, IP-throttled). | — |
| MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
| MCP_HTTP_PORT | Port for the HTTP server. | 3010 |
| MCP_HTTP_ENDPOINT_PATH | HTTP endpoint path. | /mcp |
| MCP_SESSION_MODE | HTTP session mode: stateless, stateful, or auto (resolves to stateful). The server declares stateless in code; an explicit value overrides it, while an empty or unsubstituted ${…} value falls through to stateless. | stateless |
| MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
| MCP_LOG_LEVEL | Log level (RFC 5424). | info |
| LOGS_DIR | Directory for log files (Node.js only). | <project-root>/logs |
| STORAGE_PROVIDER_TYPE | Storage backend. | in-memory |
| OTEL_ENABLED | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). | false |
See .env.example for the full list of optional overrides.
Rate limits and freshness. The keyless public tier shares an IP-throttled pool, so bursty multi-tool workflows can hit 429s under light load; the server backs off and retries, but cannot raise the ceiling — a free Demo key does. CoinGecko data refreshes roughly every 60 seconds and is not tick-level.
Running the server
Local development
Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:httpRun checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker build -t coingecko-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 coingecko-mcp-serverThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/coingecko-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
| Directory | Purpose |
|:---|:---|
| src/index.ts | createApp() entry point — registers tools/resources/prompts and inits the CoinGecko service. |
| src/config | Server-specific environment variable parsing and validation with Zod. |
| src/mcp-server/tools | Tool definitions (*.tool.ts). |
| src/mcp-server/resources | Resource definitions (*.resource.ts). |
| src/mcp-server/prompts | Prompt definitions (*.prompt.ts). |
| src/services/coingecko | CoinGecko v3 REST API service — HTTP client, retry/error mapping, response normalization, domain types. |
| tests/ | Unit and integration tests mirroring src/. |
Development guide
See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storage - Register new tools and resources via the
createApp()arrays insrc/index.ts - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
