# market-pulse-mcp

A small, focused MCP (Model Context Protocol) server that gives an LLM live crypto market data: spot prices, OHLCV candles, order book snapshots, perpetual funding rates, and a handful of technical indicators, computed from scratch. Every data source is a public, keyless exchange API, so there is nothing to configure and no account to create.

Built by Brandon Perez ([@remybanks77](https://github.com/remybanks77)) as a portfolio piece demonstrating a clean MCP server implementation: typed Python, a small dependency footprint, and indicator math written by hand instead of pulled in from pandas or ta-lib.

<!-- mcp-name: io.github.remybanks77/market-pulse-mcp -->

## What it does

market-pulse-mcp exposes eight tools over the MCP stdio transport. Tool names are
namespaced with the server name so they do not collide with the other market-data
servers a client may have installed at the same time:

| Tool | Description | Source |
| --- | --- | --- |
| `market_pulse_price(symbol)` | Current spot price, best bid/ask, 24h volume | Coinbase Exchange |
| `market_pulse_candles(symbol, granularity, limit)` | OHLCV candles | Coinbase Exchange |
| `market_pulse_orderbook(symbol, depth, include_levels)` | Best bid/ask, spread in bps, bid/ask imbalance; raw ladder opt-in | Coinbase Exchange |
| `market_pulse_funding_rate(symbol)` | Perp funding rate, mark price, open interest | Hyperliquid |
| `market_pulse_indicators(symbol, granularity, limit)` | RSI(14), EMA(20/50), ATR(14), realized volatility | Coinbase Exchange (computed locally) |
| `market_pulse_summary(symbols)` | Compact multi-asset table combining the above | Coinbase Exchange + Hyperliquid |
| `market_pulse_basis(symbols)` | Spot-perp basis in bps, contango/backwardation, funding agreement | Coinbase Exchange + Hyperliquid |
| `market_pulse_supported_assets(venue, search, limit)` | Which assets each venue covers, and which support basis | Coinbase Exchange + Hyperliquid |

Symbols are plain base tickers: `"BTC"`, `"ETH"`, `"SOL"`. A trailing `-USD` or `/USD` is tolerated and stripped, so `"BTC-USD"` and `"BTC"` are equivalent.

## Install

### From PyPI

```bash
uvx market-pulse-mcp
```

`uvx` fetches and runs the server without installing anything permanently, which is
what an MCP client config should point at. `pip install market-pulse-mcp` works too.

### From source

#### With uv (recommended)

```bash
git clone https://github.com/remybanks77/market-pulse-mcp.git
cd market-pulse-mcp
uv venv
uv pip install -e ".[dev]"
```

#### With pip

```bash
git clone https://github.com/remybanks77/market-pulse-mcp.git
cd market-pulse-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Both install a `market-pulse-mcp` console script that runs the server over stdio.

### Distribution files

`server.json` is the [official MCP registry](https://registry.modelcontextprotocol.io)
entry, published with `mcp-publisher` against the PyPI package. `manifest.json` and
`.mcpbignore` describe the same server as an [MCPB](https://github.com/modelcontextprotocol/mcpb)
bundle, which is how Smithery distributes stdio servers and how Claude Desktop installs
one in a click. The bundle declares `server.type: "uv"`, so dependencies are resolved
from `pyproject.toml` on the user's machine rather than vendored into the archive; that
keeps it around 100 KB and works on every platform without shipping compiled wheels.

## Configure in Claude Code

Add this to your project's `.mcp.json` (or run `claude mcp add`):

```json
{
  "mcpServers": {
    "market-pulse": {
      "command": "market-pulse-mcp",
      "args": []
    }
  }
}
```

If you did not install into an active virtualenv, point `command` at the venv's binary directly, for example `/path/to/market-pulse-mcp/.venv/bin/market-pulse-mcp`.

## Configure in Claude Desktop

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

```json
{
  "mcpServers": {
    "market-pulse": {
      "command": "/absolute/path/to/market-pulse-mcp/.venv/bin/market-pulse-mcp"
    }
  }
}
```

Restart Claude Desktop after saving. The `market-pulse` server should appear under the hammer/tools icon with its six tools listed.

## Example conversation

```
User: What's BTC doing right now, and is it overbought?

Claude: [calls get_price("BTC")]
        [calls compute_indicators("BTC", granularity="1h", limit=200)]

BTC is at $109,842 (bid $109,838 / ask $109,846). On the 1h chart:
  - RSI(14): 68.4, approaching overbought but not there yet (>70)
  - EMA(20) $109,510 above EMA(50) $108,220: short-term trend is bullish
  - ATR(14): $412, so a typical 1h range is roughly 0.4% of price
  - Realized vol (annualized): 47.9%

Not screaming overbought, but RSI is climbing. Want me to check the order
book for signs of resistance near current price, or pull funding rates to
see how leveraged longs are positioned?

User: Check funding, and give me a quick scan of BTC, ETH, and SOL.

Claude: [calls get_funding_rate("BTC")]
        [calls market_summary(["BTC", "ETH", "SOL"])]

Funding on BTC perps (Hyperliquid): 0.0057% per 8h (about 6.2% annualized).
Mildly long-skewed, nothing extreme.

Quick scan:
  BTC   $109,842   RSI 68.4   bullish   funding +6.2%/yr
  ETH   $3,912      RSI 61.2   bullish   funding +4.8%/yr
  SOL   $198.30     RSI 54.9   flat      funding +2.1%/yr

All three trending up on the hourly with positive funding. Nothing at a
extreme RSI level right now.
```

## Design notes

**Why hand-rolled indicator math instead of pandas or ta-lib.** The whole point of this server is to be a small, auditable dependency: `mcp` and `httpx`, nothing else. Pulling in pandas for four indicator formulas would be a much heavier dependency than the actual server logic. `market_pulse_mcp/indicators.py` implements SMA, EMA, Wilder's RSI, Wilder's ATR, and annualized realized volatility (from log returns) directly on plain Python lists, with each formula unit-tested against hand-derived fixture values so the math itself is verified, not just the wiring around it.

**Why Coinbase and Hyperliquid specifically.** Both expose full market data without an API key: Coinbase Exchange's public REST endpoints (`api.exchange.coinbase.com`) cover ticker, candles, and order book; Hyperliquid's public info API (`api.hyperliquid.xyz/info`) covers perp funding and mark prices in a single `metaAndAssetCtxs` request. That keeps this project genuinely zero-config: clone it, install it, run it, no signup.

**Rate-limit handling and caching.** Coinbase's public tier rate-limits aggressively (a few requests per second). `exchanges.py` wraps every request in a small retry-with-exponential-backoff loop that retries on HTTP 429 and 5xx responses (up to 3 attempts, doubling the backoff each time) and fails fast on other 4xx errors, since those indicate a bad request rather than a transient condition. Repeat reads are absorbed by short TTL caches (5s tickers, 20s candles, 10s perp universe) rather than by slowing calls down, and concurrent callers asking for the same key collapse into a single upstream request instead of N of them.

**Concurrency.** `market_summary` and `get_basis` fan out across symbols with `asyncio.gather` over one process-wide pooled HTTP client, rather than opening a fresh connection per call and walking symbols one at a time. Hyperliquid's `metaAndAssetCtxs` returns the entire perp universe on every request regardless of what was asked for, so it is fetched once per cache window and indexed by coin instead of being re-downloaded and discarded per symbol. An eight-symbol summary went from 2.67s to 0.24s cold, and is served from cache on repeat.

**Venue overlap.** `market_pulse_basis` needs an asset quoted on both venues. Coinbase lists roughly 400 USD spot pairs and Hyperliquid roughly 232 perps, overlapping on about 126 assets. Spot-only assets still work for price, candles, order book and indicators; perp-only assets still work for funding. Rather than leaving a model to discover that by watching symbols fail one at a time, `market_pulse_supported_assets` reports the partition and can be filtered to any one slice of it.

**Context cost as a design constraint.** Every field a tool returns is a field the calling model pays for. `market_pulse_orderbook` used to return `depth` price levels per side by default, which at its maximum meant 100 `[price, size]` pairs pushed into the context to answer a question that the spread and imbalance almost always answer; the ladder is now behind `include_levels`. For the same reason 404s are reported as "not listed on Coinbase spot" rather than echoing back a request URL and a JSON error body.

**Error handling philosophy.** Every tool catches exceptions from the exchange clients and indicator math and returns `{"error": "..."}` instead of letting a traceback propagate through the MCP transport. That gives the calling model a readable message it can act on (retry, ask the user for a different symbol, etc.) instead of an opaque tool failure.

## Tests

```bash
pytest                    # offline tests only (default; see pyproject.toml)
pytest -m integration     # also hit live Coinbase / Hyperliquid APIs
```

The offline suite (`tests/test_indicators.py`, `tests/test_exchanges.py`) is fully deterministic: indicator values are checked against fixtures worked out by hand (see the comments in each test), and exchange helper functions (symbol normalization, granularity resolution) are pure functions with no network access. The integration suite (`tests/test_integration.py`) is marked `@pytest.mark.integration` and skipped by default, since it depends on live prices and external uptime; run it explicitly when you want to confirm the client code still matches the real API shapes.

## Project layout

```
market_pulse_mcp/
  server.py       # MCPServer-based server: tool definitions, stdio entry point
  exchanges.py    # Coinbase + Hyperliquid HTTP clients, symbol/granularity helpers
  indicators.py   # RSI, EMA, ATR, realized volatility (stdlib only)
tests/
  test_indicators.py   # offline, fixture-based
  test_exchanges.py    # offline, pure-function tests
  test_integration.py  # live API tests, opt-in via -m integration
```

## License

MIT, see [LICENSE](LICENSE).