cmc-market-agent
# CMC Market Agent
**MCP server + CLI agent that puts live CoinMarketCap market data in front of LLMs.**
Built for **Build with CMC: API Hackathon, Round 2** — track **AI Agents and Automation**
([official page](https://coinmarketcap.com/api/resources/api-hackathon-2026-11/)).
An LLM's training data goes stale the day it's cut off. This project gives any
MCP-compatible LLM (Claude Desktop, VS Code, Claude Code, …) nine tools to
answer crypto questions from **live** CoinMarketCap data instead of guessing:
prices, top listings, trending coins, gainers/losers, OHLCV history, global
market totals, and the Fear & Greed index — plus a one-call market brief.
## Quick start
```bash
git clone https://github.com/melatim80186/cmc-market-agent.git
cd cmc-market-agent
npm install
npm run build
```
### Demo (no key needed)
Without an API key the server runs on **clearly-labelled mock data**, so the
demo always works:
```bash
npm run demo # exercises all 9 tools end-to-end
npm run brief # one-page market brief
npm run ask -- "price of BTC and ETH"
npm run ask -- "top gainers today"
npm run ask -- "BTC chart last 7 days"
npm test # 11 tests, mock mode, no network
npm run smoke # speaks raw MCP JSON-RPC to the server over stdio
```
### Live data (needs a free CMC API key)
```bash
cp .env.example .env # then put your key in .env — or export CMC_API_KEY
export CMC_API_KEY=your-key-here
npm run brief
```
Get a free key at <https://coinmarketcap.com/api/>. Hackathon participants
get a free **Startup tier** upgrade for the event window after registering on
DoraHacks with the email on their CMC account. The key is read **only** from
the environment — it is never written to a file and never committed
(`.gitignore` blocks `.env`).
### MCP server (Claude Desktop etc.)
```bash
npm start # stdio transport; CMC_API_KEY=... for live data
```
Add to Claude Desktop config (see `examples/claude_desktop_config.json` —
replace the path and the key):
```json
{
"mcpServers": {
"cmc-market-agent": {
"command": "node",
"args": ["/absolute/path/to/cmc-agents/dist/server.js"],
"env": { "CMC_API_KEY": "PASTE_YOUR_CMC_API_KEY_HERE" }
}
}
}
```
Then ask Claude things like *"What's BTC doing today vs ETH?"*,
*"Who are the top gainers this week?"* or *"Give me the morning market brief"* —
it will call the tools instead of guessing.
## Tools (9)
| Tool | CMC endpoint | What it does |
|---|---|---|
| `get_quote` | `/v1/cryptocurrency/quotes/latest` | Price, 24h/7d change, volume, market cap for 1+ symbols |
| `get_listings` | `/v1/cryptocurrency/listings/latest` | Top coins ranked by market cap |
| `get_trending` | `/v1/cryptocurrency/trending/latest` | Coins trending on CMC right now |
| `get_gainers_losers` | `/v1/cryptocurrency/trending/gainers-losers` | Top gainers / losers (1h, 24h, 7d, 30d) |
| `search_coin` | `/v1/cryptocurrency/map` | Resolve a symbol to CMC id, slug, rank |
| `get_ohlcv` | `/v2/cryptocurrency/ohlcv/historical` | Daily OHLCV candles, last N days |
| `get_global_metrics` | `/v1/global-metrics/quotes/latest` | Total market cap, volume, BTC/ETH dominance |
| `get_fear_greed` | `/v1/global-metrics/quotes/fear-greed/latest` | Fear & Greed index (0–100 + label) |
| `get_market_brief` | *(composes the above)* | One-call digest: top coins, top mover, Fear & Greed, totals |
Every tool response is stamped `data_source: "live" | "sandbox" | "mock"`, and
mock responses carry an explicit `mock_notice` — mock numbers can never be
mistaken for live prices.
## Project layout
```
src/
server.ts MCP server (stdio) — the 9 tools above
agent.ts CLI agent: `brief` + plain-English `ask` (keyword intent router)
demo.ts end-to-end demo of all tools
tools.ts shared tool layer (used by server + CLI)
cmc.ts thin CMC Pro API client
mock.ts clearly-labelled mock data (demo only)
config.ts env config — key from env only, mock when no key
tests/ node:test suite (mock mode, no network)
scripts/ MCP protocol smoke test (raw JSON-RPC over stdio)
examples/ Claude Desktop config
docs/ API notes + demo transcript
```
## What the CMC API made possible / where it got in the way
See [`docs/API-NOTES.md`](docs/API-NOTES.md) — required reading for the
hackathon submission note. Short version: one API covers quotes, listings,
trending, OHLCV, global metrics and sentiment, which is exactly what an
agent needs; the friction was the sandbox host returning empty replies from
this environment (so the demo falls back to labelled mock data until a real
key is present) and `/v1/cryptocurrency/map` accepting symbols but not
free-text names.
## Hackathon submission
- **Track:** AI Agents and Automation
- **Deadline:** 9 Dec 2026, 23:59 UTC · **Results:** 30 Dec 2026
- **Endpoints used:** named explicitly in the table above and in `docs/API-NOTES.md`
- **Demo:** `npm run demo` (see `docs/DEMO.md` for a transcript); a screen
recording of the live run is made once a real API key is available
- **Status:** NOT yet submitted on DoraHacks — submission needs the
builder's DoraHacks account + X post (`#BuildwithCMC`), both human steps
## License
MIT — see [LICENSE](LICENSE).
TDQS
Scored across 9 tools
Each tool targets a distinct data slice: single-coin quotes, market-cap listings, trending, gainers/losers, OHLCV, global metrics, and fear & greed. The only real overlap is get_market_brief, which aggregates several of the others, but its description clearly frames it as a one-call convenience rather than a duplicate.
Almost everything follows a clean get_<resource> snake_case pattern (get_quote, get_listings, get_ohlcv, get_global_metrics). The sole deviation is search_coin, which uses a different verb despite being a resolution/lookup operation; readable but not perfectly uniform.
Nine tools is well within the sweet spot and every tool maps to a real analytical need for a crypto market agent. There is no filler or near-duplicate padding the surface.
The read-only market-data lifecycle is largely covered: discovery (listings, trending, search), pricing (quote, OHLCV), and sentiment/aggregates (global metrics, fear & greed, brief). Gaps are minor — no exchange-level or category/metadata lookup, and search_coin is required before OHLCV, which is a slight workflow dependency rather than a missing operation.