CryptoSense MCP

Real-time crypto market intelligence for AI assistants.

CryptoSense MCP wraps the CoinGecko free API (no key needed) into a production-ready Model Context Protocol server built with FastMCP. Connect it to Claude, Cursor, Windsurf, or any MCP-compatible client and ask natural-language questions about crypto markets.

What this MCP does

All tools require a CryptoSense API key (see Authentication).

Installation

Option A — local with uv (recommended)

# 1. Clone
git clone https://github.com/your-org/cryptosense-mcp.git
cd cryptosense-mcp

# 2. Create venv and install
uv venv && uv pip install -e .

# 3. Copy and edit environment variables
cp .env.example .env
# Edit .env: set CMC_API_KEY if you have one, adjust MCP_PORT if needed

# 4. Generate your first API key
python -c "
import asyncio
from src.cryptosense.auth import generate_api_key
key = asyncio.run(generate_api_key('you@example.com'))
print('Your API key:', key)
"

# 5. Start the server
cryptosense-mcp
# or: python -m cryptosense.server

Option B — local with pip

pip install -e .
cp .env.example .env
python -m cryptosense.server

Option C — Docker

docker build -t cryptosense-mcp .
docker run -p 8000:8000 \
  -e CMC_API_KEY=your_key \
  -v cryptosense-data:/app/data \
  cryptosense-mcp

Authentication

Every tool call requires an api_key parameter with a valid CryptoSense key.

Generate a key

import asyncio
from cryptosense.auth import generate_api_key

key = asyncio.run(generate_api_key(email="you@example.com", plan="free"))
print(key)  # cs_Abc123...

Keys are stored in keys.db (SQLite). The keys.db file lives next to the server process (or at DATABASE_URL from .env).

CoinGecko API key (optional)

CoinGecko's free public API works without a key. If you experience rate limiting (30 calls/min on the free tier), sign up at https://www.coingecko.com/en/api for a free Demo API key and add it to your .env:

CG_API_KEY=CG-xxxxxxxxxxxxxxxxxxxx

The server currently uses the public endpoint. If you add a key, pass it via the x-cg-demo-api-key header in _fetch() calls.

Configure Claude Desktop

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

{
  "mcpServers": {
    "cryptosense": {
      "command": "python",
      "args": ["-m", "cryptosense.server"],
      "cwd": "/absolute/path/to/cryptosense-mcp",
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000"
      }
    }
  }
}

Or if the server is already running remotely, use the HTTP transport URL:

{
  "mcpServers": {
    "cryptosense": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Configure Cursor

Open Settings → MCP → Add new MCP server and enter:

Or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cryptosense": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Configure Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cryptosense": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}

Tool Reference & Example Prompts

price — Get coin price

"What is the price of Bitcoin?" "How much is Ethereum worth in EUR?" "Show me Solana's 24h change and market cap."

price(coin="bitcoin", currency="usd", api_key="cs_...")
# → { "coin": "bitcoin", "price": 67420.0, "market_cap": 1.32T, "change_24h_percent": 2.4, ... }

top_coins — Top coins by market cap

"Show me top 10 coins." "What are the top 20 cryptocurrencies by market cap?" "List the 5 biggest coins in EUR."

top_coins(limit=10, currency="usd", api_key="cs_...")
# → { "coins": [{ "rank": 1, "name": "Bitcoin", "price": 67420, ... }, ...] }

trending — Trending now

"What is trending in crypto today?" "Which coin is everyone searching for?" "Show me the hottest altcoins right now."

trending(api_key="cs_...")
# → { "trending_coins": [{ "name": "Pepe", "symbol": "PEPE", "market_cap_rank": 54, ... }] }

portfolio_value — Portfolio calculator

"Calculate my portfolio: 0.5 BTC, 5 ETH, 100 SOL." "How much is my crypto worth? I have 1 bitcoin and 10 ethereum." "What is my total if I hold 0.1 BTC, 500 DOGE, and 2 ETH?"

portfolio_value(
    holdings={"bitcoin": 0.5, "ethereum": 5, "solana": 100},
    currency="usd",
    api_key="cs_...",
)
# → { "total_value": 54230.00, "best_performer": {...}, "breakdown": [...] }

compare — Side-by-side comparison

"Compare Bitcoin and Ethereum." "Which performs better: Solana, Avalanche, or Polkadot?" "Show me BTC vs ETH vs BNB."

compare(coins=["bitcoin", "ethereum", "solana"], currency="usd", api_key="cs_...")
# → { "comparison": [...], "best_performer_24h": "solana", "worst_performer_24h": "bitcoin" }

market_overview — Global snapshot

"What is the total crypto market cap?" "What is Bitcoin's market dominance today?" "Give me a global crypto summary."

market_overview(api_key="cs_...")
# → { "total_market_cap_usd": 2.45T, "btc_dominance_percent": 52.3, ... }

Environment Variables

Error Handling

All tools return a friendly {"error": "..."} dict on failure — no stack traces are ever returned to the client. Handled conditions:

• Invalid / missing API key → prompt to generate one

• Coin not found → suggests using the full CoinGecko ID

• Rate limit (429) → asks to wait and retry

• Network errors → descriptive message

• Invalid parameters → caught before the API call

License

MIT