Metadata-Version: 2.4
Name: ark-market-data-mcp
Version: 0.2.0
Summary: MCP server for streaming crypto market data via WebSocket
Author-email: arkhamides <joearchondis@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/arkhamides/mcp-market-data
Project-URL: Repository, https://github.com/arkhamides/mcp-market-data
Project-URL: Documentation, https://github.com/arkhamides/mcp-market-data#readme
Keywords: mcp,market-data,websocket,streaming
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.1.0
Requires-Dist: websockets>=12.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: starlette>=0.36.0
Provides-Extra: historical
Requires-Dist: ccxt>=4.0.0; extra == "historical"
Dynamic: license-file

# Ark Market Data MCP

An MCP (Model Context Protocol) server that streams real-time market data to Claude via WebSocket connection.

## Features

- **Real-time Market Data Streaming** - Connects to a WebSocket server and buffers incoming market data
- **OHLCV History** - Aggregates live stream into 1m/5m candles persisted to a local SQLite database
- **Historical Seeding** - One-command backfill from Binance (default 6 months, fully configurable)
- **MCP Integration** - Works seamlessly with Claude via the Model Context Protocol
- **Configurable WebSocket URL** - Supports environment variable configuration for flexible deployment
- **In-memory Buffering** - Efficiently buffers up to 500 messages with configurable size
- **Auto-reconnect** - Automatically reconnects on connection failures with exponential backoff

## Installation

### Via PyPI

```bash
pip install ark-market-data-mcp
```

### From Source

```bash
git clone https://github.com/arkhamides/mcp-market-data.git
cd ark-market-data-mcp
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
```

## Quick Start

### 1. Set up your WebSocket endpoint

```bash
export WS_URI=ws://your-websocket-url.com
```

### 2. Add to Claude

```bash
claude mcp add ark-market-data ark-market-data-mcp
```

### 3. Use with Claude

```bash
claude chat
```

Ask Claude to use the market data tools, e.g., "What's the latest market data?"


## Seeding Historical Data

Before running backtests, seed the local database with historical candles from Binance.

```bash
# Install the historical extra
pip install ark-market-data-mcp[historical]
# or just: pip install ccxt

# Default: BTC/USDT, 1m candles, last 6 months
python scripts/seed_historical.py

# Custom symbol / resolution
python scripts/seed_historical.py --symbol ETH/USDT --resolution 5m

# Custom date range
python scripts/seed_historical.py --start 2024-01-01 --end 2024-07-01

# Custom look-back window
python scripts/seed_historical.py --days 90

# Match your live stream symbol format
python scripts/seed_historical.py --symbol BTC/USDT --store-symbol BTC-USD
```

Candles are written to `~/.ark-market-data/ohlcv.db` (override with `DATA_DIR` env var).
Re-running is safe — existing candles are upserted, so gaps are filled without duplicates.

## Available Tools

The MCP server exposes the following tools for Claude:

**Real-time stream**
- **`get_latest_message`** - Get the most recent market message from the stream
- **`get_recent_messages`** - Get the last N messages (default: 10, max: 500)
- **`get_stream_status`** - Check WebSocket connection status and buffer statistics
- **`clear_buffer`** - Clear the message buffer

**Order book analysis**
- **`get_market_summary`** - Best bid/ask, spread, volume imbalance, price change %

**Alerts**
- **`set_price_alert`** - Trigger when a symbol crosses a price threshold
- **`set_percent_change_alert`** - Trigger when price moves by a % over N messages
- **`get_alerts`** - List all active and triggered alerts

**Historical OHLCV**
- **`get_ohlcv`** - Recent closed candles for a symbol and resolution (1m/5m)
- **`get_candles_range`** - Candles between two Unix timestamps

**Backtesting**
- **`run_backtest`** - Simulate a trading strategy against historical candles; returns P&L, max drawdown, and full trade log

## Connecting for the users of the app

### Remote server connection
```
https://mcp-market-data.com/mcp?api=YOUR_API_KEY
```

### Local server connection

```bash
source venv/bin/activate
```

```bash
# Defaults to stdio
python3 -m ark_market_data_mcp

# Explicitly use stdio
python3 -m ark_market_data_mcp stdio

# Use HTTP transport (Docker, remote clients)
python3 -m ark_market_data_mcp http

```

## Development

### Test with MCP Inspector

```bash
# Terminal 1: Start the server
source venv/bin/activate
WS_URI=ws://your-websocket-url.com python3 -m ark_market_data_mcp

# Terminal 2: Open the MCP Inspector
npx @modelcontextprotocol/inspector
```

Open `http://localhost:5173` in your browser to test tools and messages.

### Run tests

```bash
pytest
```

## Architecture

```
┌─────────────────────────┐
│     Claude (User)       │
└────────────┬────────────┘
             │
             │ (via stdio)
             │
┌────────────▼────────────┐
│   MCP Server (Python)   │
│  - Listens on stdio     │
│  - Exposes tools        │
└────────────┬────────────┘
             │
             │ (WebSocket)
             │
┌────────────▼───────────────┐
│   Ark Market Data Server   │
│    (Remote WebSocket)      │
└────────────────────────────┘
```


## Troubleshooting

### Connection Refused

If you see "Connection refused" errors:
- Ensure your WebSocket server is running
- Verify the `WS_URI` environment variable is set correctly
- Check firewall settings if using a remote server

### No Messages Received

- Verify the WebSocket server is sending data in the expected format
- Check the logs: they show all incoming messages
- Use the `get_stream_status` tool to verify connection status

### MCP Tools Not Showing Up

- Restart Claude after adding the MCP
- Check that the server starts without errors
- Verify the MCP was added correctly: `claude mcp list`

## License

MIT

## Author

arkhamides
