coingecko-mcp-server

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

Resources

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

Related MCP server: crypto-data-mcp

Capability reference

coingecko_search_coins tool

• Tickers are not unique (many coins share ETH/USDC) — returns ranked candidates with id, symbol, name, and marketCapRank to disambiguate

• Returns the top 25 matches by relevance; enrichment.truncated plus shown/cap disclose when the list is capped

• An empty result is a normal outcome, not an error — enrichment.notice suggests broadening the query

coingecko_get_prices tool

• Batch up to 250 slugs across one or more currencies (vs_currencies defaults to ["usd"]) in a single call

• 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 — missing lists unresolved ids so a typo reads as "unresolved," not "nonexistent"

• Unsupported currency codes are silently dropped upstream and surfaced via enrichment.notice

• lastUpdatedAtUnixSec, when present, is Unix seconds — coingecko_get_market_chart's point timestamps are milliseconds

• Throws all_missing only when no requested id resolves

coingecko_list_markets tool

• Sort by market cap, volume, or 24h price change, ascending or descending, via order

• Optional category filter — pass a categoryId from coingecko_list_categories

• Pagination via page and per_page (default 50, max 250 rows); enrichment.truncated discloses when a page fills

• Per-coin fields include price, cap, volume, 1h/24h/7d change, supply, and ATH/ATL

• Throws unknown_category when a category filter returns empty — CoinGecko returns empty rather than erroring on an unrecognized slug

coingecko_get_coin tool

• Six sections — profile, market, links, developer, community, sentiment; sections trims the response to just what's needed (the full record is large)

• Market figures are denominated in vs_currency (defaults to usd)

• profile.categories are display names (e.g. "Layer 1 (L1)") — distinct from the categoryId slugs coingecko_list_categories returns

• Sparse upstream fields are omitted rather than fabricated

• Throws coin_not_found when the slug isn't recognized upstream

coingecko_get_market_chart tool

• recent mode: last N days (or "max"); granularity auto-scales by span — ≤1 day → ~5-min, 2–90 → hourly, >90 → daily

• range mode: an explicit window via from/to as Unix seconds

• Returns timestamped point arrays for price, market cap, and volume in vs_currency (defaults to usd)

• Point timestamps are Unix milliseconds — coingecko_get_prices's lastUpdatedAtUnixSec is seconds

• Throws invalid_range on a mode/parameter mismatch, coin_not_found when the slug isn't recognized

coingecko_get_trending tool

• No parameters — 24-hour trending coins by search volume, each with marketCapRank, priceUsd, priceBtc, and priceChangePercentage24hUsd when available

• Upstream reports market cap and volume as pre-formatted display strings, not numbers — those fields are omitted rather than presented as numeric data

• nftCount reports 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 (default usd) scopes only total market cap and volume; dominance and the 24h change percentages are always USD-denominated upstream

• Throws unsupported_currency when the requested currency has no entry in upstream's per-currency maps — /global has 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_contains filters the ~800-category list locally by whitespace-separated tokens — case- and punctuation-insensitive, every token must appear in the name

• enrichment.totalCount reports the total category count before any local filter

• Returned categoryId values are what coingecko_list_markets's category param expects

• A filter that matches nothing returns enrichment.notice suggesting 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 with coingecko_search_coins

• Throws coin_not_found when 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: coin required — 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 on the rate-limited public tier — 429s, 5xx, and timeouts retry; Retry-After is honored

• Three distinct upstream error shapes mapped to typed reasons (404 → coin_not_found, 429 → rate_limited, the /simple/price silent miss handled as a missing field, not an error)

Agent-friendly output:

• Search-before-query enforced through descriptions — every ID-keyed tool states slugs-not-tickers and points back to coingecko_search_coins

• Provenance and graceful degradation — coingecko_get_prices reports unresolved ids and dropped currencies instead of failing; truncation and applied filters are disclosed via enrichment

• 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/mcp

Prerequisites

• 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

1. Clone the repository:

git clone https://github.com/cyanheads/coingecko-mcp-server.git

2. Navigate into the directory:

cd coingecko-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# the server runs with no .env at all; edit only to set COINGECKO_API_KEY

Configuration

The server runs with zero configuration. The one server-specific variable is optional:

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:http

• Run 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-server

The 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

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools and resources via the createApp() arrays in src/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 test

License

Apache-2.0 — see LICENSE for details.