coin-mcp

coin-mcp

English · 中文

A comprehensive cryptocurrency market-data MCP server. Six data sources, 49 tools, 8 prompt templates, 3 resources — wired together so an LLM can answer almost any "what's the market doing?" question with a single call.

Table of contents

• Why coin-mcp
• What it can answer
• Installation
• Architecture
• Tool catalog (49)
• Prompt templates (8)
• Resources (3)
• Configuration
• MCP client integration
• Transports
• Caching layer
• Security model
• Project structure
• Testing
• Roadmap
• License
• Acknowledgments

Why coin-mcp

Most crypto MCP servers are thin wrappers around a single API and hit a wall the moment a user asks anything that requires combining sources. coin-mcp is built around a different premise: a strong AI assistant needs complementary data sources behind one consistent contract.

Plus a tiered HTTP cache that keeps you safely under CoinGecko's free-tier rate limit, and a multi-transport runtime (stdio / SSE / streamable-HTTP).

What it can answer

A non-exhaustive sample of questions a connected LLM can resolve in 1–3 tool calls:

• "What is BTC trading at right now?" → get_price
• "Compare BTC's price across Coinbase, Kraken, OKX and DexScreener and tell me the spread." → compare_prices
• "Give me a 30-day chart and run RSI, MACD and Bollinger on it." → get_market_chart + compute_indicators
• "Where is the best bid for ETH/USDT across exchanges?" → get_consolidated_orderbook
• "Funding rates for the BTC perp on Binance, OKX, Bybit, Bitmex — who's paying who?" → compare_funding_rates
• "What protocols are leading TVL on Solana right now?" → list_protocols(chain="Solana")
• "Find me yield pools paying > 10% APY on stablecoins with > $5M TVL." → list_yield_pools
• "Is the market fearful or greedy today?" → get_fear_greed_index
• "Is everything healthy? I'm seeing weird data." → health_check
• "Which public companies hold BTC?" → get_companies_holdings

Installation

Prerequisites

• Python 3.10+ (python3 --version to check)
• Git
• One of:
  • uv (recommended — handles Python toolchain, venv, lockfile in one tool)
  • pip + a virtualenv

uv install (one line, all platforms):

curl -LsSf https://astral.sh/uv/install.sh | sh        # macOS / Linux
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows PowerShell

Option 1 — uv (recommended)

git clone https://github.com/ymylive/coin-mcp.git
cd coin-mcp
uv sync                                # creates .venv, installs from uv.lock
uv run coin-mcp                        # starts the server on stdio

uv sync reads pyproject.toml + uv.lock and installs everything (mcp, httpx, ccxt) into a project-local .venv/. No system pollution.

Option 2 — pip + venv

git clone https://github.com/ymylive/coin-mcp.git
cd coin-mcp
python3 -m venv .venv
source .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .                       # editable install, deps resolved fresh
coin-mcp                               # starts the server on stdio

Option 3 — install directly from GitHub (no clone)

uv tool install git+https://github.com/ymylive/coin-mcp.git
coin-mcp                               # available on PATH

This puts the coin-mcp console script on your PATH globally without cluttering any project directory. Best for "I just want to point Claude Desktop at it."

Optional: install dev/test extras

If you want to run the test suite or hack on the code:

uv sync --extra dev                    # adds pytest + pytest-asyncio
uv run pytest                          # 29 tests, all should pass

Verify the installation

A 5-second sanity check that all tools registered correctly:

uv run python -c "
import asyncio, server
async def main():
    tools = await server.mcp.list_tools()
    prompts = await server.mcp.list_prompts()
    resources = await server.mcp.list_resources()
    print(f'{len(tools)} tools / {len(prompts)} prompts / {len(resources)} resources')
asyncio.run(main())
"
# Expected: 49 tools / 8 prompts / 3 resources

CLI help is also one command away:

uv run coin-mcp --help

Common pitfalls

Architecture

                        ┌──────────────────────────────┐
                        │       LLM / MCP client       │
                        │   Claude · Cursor · custom   │
                        └──────────────┬───────────────┘
                                       │ JSON-RPC over stdio / SSE / HTTP
                        ┌──────────────▼───────────────┐
                        │       FastMCP server         │
                        │   49 tools · 8 prompts · 3   │
                        │   resources · multi-transport│
                        └──────────────┬───────────────┘
                                       │
                ┌──────────────────────┼──────────────────────┐
                │                      │                      │
       ┌────────▼─────────┐   ┌────────▼────────┐   ┌────────▼────────┐
       │ HTTP layer       │   │  CCXT runtime   │   │  Local compute  │
       │ httpx + tiered   │   │  Bounded LRU    │   │  Indicators     │
       │ TTL LRU cache    │   │  + per-id RLock │   │  (no I/O)       │
       │ + auth-aware key │   │  + pre-warm     │   │                 │
       └────────┬─────────┘   └────────┬────────┘   └─────────────────┘
                │                      │
   ┌────────────┼──────────────┐       │
   ▼            ▼              ▼       ▼
CoinGecko  DefiLlama  DexScreener   100+ exchanges
                                    (Binance, OKX, Coinbase,
                                     Kraken, Bybit, …)

Key design choices:

• One tool per endpoint, with rich AI-facing docstrings. No clever endpoint factories — the docstrings ARE the API contract that the LLM reads to decide which tool to call. Forty-nine docstrings is a feature, not a bug.
• {"error": "..."} envelope contract. Every HTTP-backed tool returns either upstream JSON or an error envelope. The cache never caches errors. The LLM never raises.
• Path-injection guards on every URL-interpolated parameter. Coin IDs, protocol slugs, addresses are validated against strict regexes before any HTTP call.
• Per-exchange RLock + pre-warmed load_markets(). Concurrent CCXT calls don't race the lazy markets table.
• Auth-aware cache key. Header values for known auth headers are hashed into the cache key — multi-tenant deployments don't leak.

Tool catalog (49)

Aggregated market data — CoinGecko (18)

Real-time per-exchange — CCXT (7)

Derivatives extensions — CCXT (3)

DeFi-native — DefiLlama (9)

DEX-side — DexScreener (5)

Cross-source aggregation (3)

Sentiment (1)

Local technical indicators (1)

Cache observability (2)

Prompt templates (8)

Prompts are parameterized workflows the user can pick from a UI; they expand into ready-made multi-step instructions the LLM executes using tools.

Resources (3)

Static reference data the client can attach to the LLM's context:

• coin-mcp://exchanges/ccxt — JSON list of all CCXT-supported exchange IDs
• coin-mcp://coins/popular-ids — markdown table mapping common ticker symbols to CoinGecko IDs
• coin-mcp://chains/dex-supported — markdown list of chain IDs DexScreener accepts

Configuration

All env vars are optional.

A .env.example is provided. Copy to .env and edit if you have a key.

MCP client integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coin-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/coin-mcp",
        "run",
        "coin-mcp"
      ],
      "env": {
        "COINGECKO_API_KEY": "your-optional-key"
      }
    }
  }
}

Restart Claude Desktop. The 49 tools, 8 prompts and 3 resources will appear.

Cursor

Cursor's MCP support uses the same JSON shape. Place the snippet in your Cursor settings under mcp.servers. For remote use, run the server with --transport sse or --transport streamable-http and point Cursor at the URL.

Custom client

Any MCP-compatible client works. The server speaks the standard MCP JSON-RPC over your transport of choice.

Transports

# stdio (default, for local IDE / Claude Desktop integration)
coin-mcp

# Server-Sent Events
coin-mcp --transport sse --host 127.0.0.1 --port 8000

# Streamable HTTP (for hosted / remote use)
coin-mcp --transport streamable-http --host 127.0.0.1 --port 8000

# Public bind (with no auth) — REQUIRES explicit flag and prints a stderr WARNING
coin-mcp --transport streamable-http --host 0.0.0.0 --port 8000 --allow-public

There is no built-in authentication. If you bind to a non-loopback host, put a reverse proxy with auth in front (Caddy, nginx, Traefik, Cloudflare Access, etc.) or restrict via firewall. The --allow-public flag is a deliberate footgun guard.

Caching layer

A tiered TTL cache sits transparently behind every HTTP call so the LLM can fan out without burning your CoinGecko quota.

LRU-bounded at 2,000 entries. Cache key includes the URL, sorted query params, and a sha-256 digest of any auth header values — so two clients with different keys never share a cache entry. Errors are never cached. Hits return a deep copy so callers can mutate without poisoning. Inspect at runtime via the cache_stats MCP tool.

Security model

coin-mcp is data-only — there is no transaction signing, no private-key handling, no on-chain writes. The threat surface is therefore narrow but worth being honest about:

• Path-injection guards on every URL-interpolated parameter (coin IDs, slugs, addresses). Invalid input returns {"error": "invalid <kind>"} without making the HTTP call.
• compute_indicators row cap at 5,000 (MAX_OHLCV_ROWS) prevents memory blowups from prompt-injected upstream data.
• CCXT exchange cache bounded (LRU 16) so an LLM can't force allocation of all 111 exchanges.
• Network transports refuse non-loopback bind without --allow-public and emit a stderr WARNING when the flag is given.
• Cache key is auth-aware — auth headers contribute to the key via sha-256 digest. Multi-tenant safe.
• No emoji of stdout in stdio mode — every log goes to stderr, so JSON-RPC framing is never corrupted.

If you find a security issue, please open an issue rather than a PR for non-trivial cases.

Project structure

coin-mcp/
├── server.py                   # Entrypoint — wires modules together
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── coin_mcp/
│   ├── core.py                 # FastMCP instance, helpers, instructions block
│   ├── coingecko.py            # 18 CoinGecko tools
│   ├── ccxt_tools.py           # 7 CCXT tools
│   ├── derivatives.py          # 3 funding/OI tools
│   ├── defillama.py            # 9 DefiLlama tools
│   ├── dexscreener.py          # 5 DexScreener tools
│   ├── aggregate.py            # 3 cross-source tools
│   ├── sentiment.py            # 1 Fear & Greed tool
│   ├── indicators.py           # 1 local-compute tool
│   ├── cache.py                # 2 cache-introspection tools + the cache itself
│   ├── prompts.py              # 8 workflow templates
│   ├── resources.py            # 3 static-reference resources
│   └── transport.py            # CLI for stdio / SSE / streamable-HTTP
└── tests/
    ├── conftest.py             # Autouse cache-clear + mcp_server fixture
    ├── test_registry.py        # Tool count / instructions / prompt-ref sanity
    ├── test_cache_routing.py   # TTL routing table + no-shadowing
    ├── test_indicators.py      # Wilder RSI textbook vector, 5-col fallback, DoS cap
    ├── test_http_envelope.py   # is_error truthy semantics + error not cached
    └── test_validators.py      # Path-injection rejection (CG/DexScreener)

Testing

uv sync --extra dev
uv run pytest
# 29 passed

The high-ROI tests cover:

• Every registered tool appears in the instructions table (LLM discoverability)
• Every prompt body references only real tool names and real parameters
• Cache TTL routing for 17 representative URLs
• Cache no-shadowing (/coins/markets vs /coins/{id} vs /market_chart)
• Wilder RSI matches the textbook 14-close reference vector (~70.46)
• 5-column OHLCV input doesn't crash OBV
• compute_indicators rejects > 5,000 rows
• is_error truthy semantics
• HTTP error responses are not cached
• Path-injection on CoinGecko / DexScreener tools is rejected before any HTTP call

Roadmap

Tracked but not yet built:

• Whale-transaction monitoring (Whale Alert)
• Etherscan / blockchain-explorer-style read-only RPC
• News + social aggregation (CryptoPanic / Santiment)
• Aggregated open-interest history (cross-exchange)
• Optional READ-ONLY signed requests for higher-tier API keys

If you have a specific data source you want integrated, open an issue with the API spec.

License

MIT — see LICENSE for the full text.

Acknowledgments

This project stands on shoulders.

• Model Context Protocol — Anthropic's open standard for AI ↔ tool wiring
• CoinGecko API — the most generous free crypto-data tier on the internet
• CCXT — the unified exchange library that makes 100+ venues feel like one
• DefiLlama — DeFi data infrastructure as a public good
• DexScreener — DEX-side market data with no auth required
• Alternative.me — the Crypto Fear & Greed Index

And all the prior MCP-server projects whose design choices we studied:doggybee/mcp-server-ccxt for the tiered cache pattern,QuantGeekDev/coincap-mcp for showing prompts matter,heurist-network/heurist-mesh-mcp-server for multi-transport precedent,the official CoinGecko MCP for dynamic tool discovery as an idea worth pursuing later.