Skip to main content
Glama
cmc-market-agent

cmc-market-agent

by melatim80186
README.md
# 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

A3.6/5.0

Scored across 9 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues