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

Tool	Description
price	Current price, market cap, volume & 24h change for any coin
trending	Top 10 trending coins by search volume (last 24 h)
market_overview	Global market cap, BTC/ETH dominance, 24h change
top_coins	Top N coins by market cap with full stats
compare	Side-by-side comparison of 2+ coins
portfolio_value	USD value of your holdings with best/worst performer

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:

Field	Value
Name	CryptoSense
Type	HTTP
URL	http://localhost:8000/mcp

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

Variable	Default	Description
CMC_API_KEY	—	CoinMarketCap API key (optional, reserved for future CMC tools)
MCP_HOST	0.0.0.0	Server bind address
MCP_PORT	8000	Server port
DATABASE_URL	keys.db	Path to the SQLite database
CRYPTOSENSE_ENABLE_KEYGEN	—	Set to true to expose the create_api_key admin tool

---

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