Tickscope
Real-time, free crypto market data for any AI agent — via MCP.
Open source Open in the app JSON README (API)
About
Real-time, free crypto market data for any AI agent — via MCP.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- seungdori
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Stars
- 1
- Open pull requests
- 1
- Last push
- 2026-06-23T00:33:25Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:22
- Updated
- 2026-08-29 04:01:22
- Origin id
io.github.seungdori/tickscope-mcp
README
<!-- mcp-name: io.github.seungdori/tickscope-mcp -->
<div align="center">
# Tickscope MCP
**Real-time, free crypto market data for any AI agent — via MCP.**
[](https://pypi.org/project/tickscope-mcp/)
[](https://pypi.org/project/tickscope-mcp/)
[](LICENSE)
[](https://github.com/seungdori/tickscope-mcp/actions/workflows/ci.yml)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](https://modelcontextprotocol.io)
**English** · [한국어](README.ko.md) · [中文](README.zh-CN.md) · [日本語](README.ja.md)
<!-- Live Claude Code walkthrough — see examples/RECORDING.md -->
</div>
Tickscope is a self-hostable [Model Context Protocol](https://modelcontextprotocol.io) server that gives any MCP client (Claude Code, Cursor, Codex, Gemini CLI, …) **real-time and historical crypto market data for free**. It keeps exchange WebSocket connections warm in the background, so your agent reads prices that are fresh to the sub-second, straight from a live connection. The same server covers **73 technical indicators** and **chart-structure recognition**, with no API keys.
> ⚠️ Educational/research tool. It does not provide financial, investment, or trading advice, and it does not guarantee data accuracy or timeliness.
---
## Contents
- [Why](#why) · [See it run](#see-it-run) · [30-second install](#30-second-install)
- [Supported exchanges](#supported-exchanges) · [Tools](#tools) · [Indicators](#indicators-73) · [Structure recognition](#structure-recognition)
- [Example prompts](#example-prompts) · [Configuration](#configuration) · [Development](#development) · [Roadmap](#roadmap)
## Why
Trading agents are exploding, yet their data layer stays fragmented, REST-poll-only, and often locked behind a paywall. Tickscope gives those agents **real-time, free market data** from one server — many exchanges, no API keys.
## See it run
```bash
uv run examples/demo.py # live BTC/USDT walkthrough (no API keys)
uv run examples/demo.py ETH/USDT 4h
```
A colorized terminal walkthrough — cold→warm freshness (REST → WebSocket), indicators with signals, divergence, market structure, and support/resistance — against live Binance/Bybit/OKX. See [examples/RECORDING.md](examples/RECORDING.md) to turn it into the GIF above.
## 30-second install
```bash
uvx tickscope-mcp
```
Register it with your client (Claude Code example, [`examples/claude_code_config.json`](examples/claude_code_config.json)):
```json
{
"mcpServers": {
"tickscope": {
"command": "uvx",
"args": ["tickscope-mcp"],
"env": {
"TICKSCOPE_EXCHANGES": "binance,bybit,okx",
"TICKSCOPE_DEFAULT_EXCHANGE": "binance"
}
}
}
}
```
Cursor, Codex and Gemini CLI use the same `command`/`args`/`env` shape in their respective MCP config files.
## Supported exchanges
| Exchange | REST | WebSocket |
|---|:---:|:---:|
| Binance | ✅ | ✅ |
| Bybit | ✅ | ✅ |
| OKX | ✅ | ✅ |
Any [ccxt](https://github.com/ccxt/ccxt)-supported exchange can be enabled via `TICKSCOPE_EXCHANGES`. Public data only — no keys required.
## Tools
| Tool | What it does |
|---|---|
| `list_exchanges` | Configured exchanges + default |
| `list_symbols` | Tradable symbols (filter by quote/search) |
| `get_ticker` | Current price snapshot (primary quote tool) |
| `get_recent_trades` | Recent executed trades from the live buffer |
| `get_ohlcv` | Historical candles (DuckDB-cached) |
| `get_orderbook` | Order book snapshot + spread |
| `compute_indicators` | 73 indicators (RSI/MACD/Supertrend/WaveTrend/Squeeze/…) with derived signals |
| `detect_divergence` | Regular/hidden bullish & bearish divergence (price vs oscillator) |
| `detect_cross` | Pine-style `ta.crossover`/`ta.crossunder` between any two series |
| `detect_patterns` | Candlestick patterns (engulfing, hammer, stars, …) with bias |
| `analyze_structure` | Market structure: swings, trend, BOS / CHoCH |
| `find_support_resistance` | Clustered support/resistance zones from pivots |
| `deep_analyze` | Multi-timeframe read: trend confluence + market-state context + historical signal performance, with a synthesized verdict |
| `screen_market` | Scan many symbols by indicator/price filters |
| `get_aggregated_price` | Volume-weighted price + cross-exchange spread (arbitrage) |
| `get_funding_rate` | Perpetual funding rate |
| `watch_symbol` | Pre-warm a live subscription (optional) |
| `get_watched_symbols` | Active subscriptions + buffer state |
| `server_status` | Health / diagnostics |
Every market-data response includes `source` (`websocket`|`rest`), `age_ms`, and `timestamp` so the freshness is always provable.
### Indicators (73)
- **MAs / overlays:** `sma ema wma smma dema tema hma vwma zlema alma kama trima lsma vidya t3 vwap vwapbands bbands donchian keltner supertrend ichimoku psar`
- **Momentum:** `rsi stochrsi macd ppo stoch cci willr roc mom tsi ao cmo uo dpo trix coppock kst fisher rvi mfi wavetrend squeeze qqe crsi stc elderray zscore linregslope`
- **Volatility:** `atr natr stdev hv chop ulcer massindex`
- **Volume:** `obv adl cmf chaikinosc eom fi pvt vo klinger`
- **Trend:** `adx dmi aroon vortex`
- **Structure:** `heikinashi pivots`
Specs are `"name:p1,p2"` and also accept **Pine Script syntax** — `ta.rsi(14)`, `ta.ema(20)`, `ta.wt(10,21)`, `ta.sqz` — so TradingView users can paste familiar expressions. Derived signals include overbought-oversold state, MACD/PPO/WaveTrend/QQE cross, zero-line cross for oscillators, Supertrend/PSAR direction & flip, squeeze on/off, DMI/Heikin-Ashi trend, and Ichimoku cloud position. Includes crypto/Pine favorites (WaveTrend, TTM Squeeze, QQE, Connors RSI, Schaff Trend Cycle, VIDYA, T3). Adding a new indicator is a one-line `REGISTRY` declaration.
### Structure recognition
On top of numeric indicators, Tickscope describes *what the chart is doing*: `detect_patterns` names candlestick patterns (engulfing, hammer/hanging man, doji family, morning/evening star, three soldiers/crows, …) with their bias; `analyze_structure` returns swing highs/lows labeled HH/HL/LH/LL, the inferred trend, and Break-of-Structure / Change-of-Character events (SMC-style); `find_support_resistance` clusters swing pivots into support/resistance zones with touch counts. These give an agent the vocabulary to describe a chart the way a trader would.
### Deep analysis
`deep_analyze` answers a question about a symbol in one call, instead of making the agent chain a dozen tools. It returns:
- **Multi-timeframe trend confluence** — the same symbol read across a 1d/4h/1h ladder, with whether the timeframes agree or conflict.
- **Market-state context** — where price sits in its recent range (percentile), the trend state (`trending_up` / `trending_down` / `ranging`, from ADX + Kaufman efficiency ratio), and the volatility state (from ATR percentile), so a bare "RSI 30" reads against the conditions it showed up in.
- **Historical signal performance** — for the current divergence, the forward-return distribution of every past *confirmed* occurrence on this symbol/timeframe (count, win rate, median). A strictly causal event study — no look-ahead, no repaint.
- **A synthesized verdict** — bias, confidence, timeframe agreement, the execution-timeframe market state, and explicit caveats, all computed deterministically in Python so the call never hinges on the model eyeballing raw numbers.
`compute_indicators` now carries the same market-state context inline (it's ~free), and signal history is memoized per closed bar, so warm reads stay fast. Clients that support MCP prompts expose this as a slash command — `/mcp__tickscope__deep_analyze` (symbol + timeframe) — to trigger a full read on demand.
### Resources
Supporting clients can also read live state as MCP resources: `tickscope://status`, `tickscope://watched`, and the template `tickscope://ticker/{exchange}/{symbol}`.
## Example prompts
- "What's BTC/USDT trading at on Binance right now, and the 24h change?"
- "Should I care about this SOL/USDT setup? Do a deep, multi-timeframe read."
- "Is there an RSI divergence on BTC/USDT 4h — and how has that signal performed on this pair before?"
- "Screen the top 50 USDT pairs by volume for ones with RSI below 30."
- "Map the key support/resistance on ETH/USDT 4h and tell me if the structure just broke (BOS/CHoCH)."
- "What's the perpetual funding rate for BTC on Bybit right now — is it overheated?"
- "Compare BTC/USDT across Binance, Bybit and OKX and show the arbitrage spread."
See [`examples/demo_prompts.md`](examples/demo_prompts.md) for a fuller recipe book (deep analysis, signal backtests, screening, monitoring, strategy checks).
## Configuration
All settings are environment variables (see [`.env.example`](.env.example)):
| Variable | Default | Description |
|---|---|---|
| `TICKSCOPE_EXCHANGES` | `binance,bybit,okx` | Enabled exchanges (comma-separated) |
| `TICKSCOPE_DEFAULT_EXCHANGE` | `binance` | Default when `exchange` is omitted |
| `TICKSCOPE_MAX_WATCHED_SYMBOLS` | `25` | Max concurrent WS subscriptions (LRU evicted) |
| `TICKSCOPE_RING_BUFFER_SIZE` | `1000` | Per-symbol trade buffer size |
| `TICKSCOPE_OHLCV_CACHE_PATH` | `~/.tickscope/ohlcv.duckdb` | DuckDB cache file |
| `TICKSCOPE_OHLCV_CACHE_TTL_S` | `60` | Freshness window for the newest candle |
| `TICKSCOPE_REST_RETRIES` | `3` | Retry attempts for transient REST errors (rate limit / network) |
| `TICKSCOPE_SCREEN_CONCURRENCY` | `5` | Max concurrent symbols during screening/aggregation |
| `TICKSCOPE_TRANSPORT` | `stdio` | `stdio` or `http` |
| `TICKSCOPE_LOG_LEVEL` | `INFO` | Log level |
## Development
```bash
uv venv && uv pip install -e ".[dev]"
pytest # ~100 unit + MCP-integration tests (live excluded)
pytest -m live # live exchange tests (Binance/Bybit/OKX, run locally)
ruff check . && mypy # lint + type gates
```
Tests cover indicator math against reference values, service cache/auto-watch logic, the full MCP tool path (`tests/test_mcp_integration.py` calls tools through `mcp.call_tool`), price-structure recognition, and a live suite that exercises the whole stack against real exchanges. See [CONTRIBUTING.md](CONTRIBUTING.md) for the project layout and contribution flow.
## Roadmap
- [x] Pine Script-style indicator mapping (`ta.rsi`, `ta.crossover`, …)
- [x] 73 indicators + candlestick patterns + market structure (BOS/CHoCH)
- [x] Multi-exchange aggregation (weighted price / spread)
- [x] MCP resource push for watched symbols
- [ ] Anchored / session VWAP
- [ ] More exchanges (Kraken, Bitget, Gate, …)
- [ ] Agent Skill (`SKILL.md`) wrapper
## Contributing
Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). Keep dependencies minimal and the v1 scope read-only (public data, no order execution, no API secrets).
## License
[MIT](LICENSE) © Tickscope contributors.
## Disclaimer
This tool is for **educational and research purposes only**. It is not financial, investment, or trading advice. Market data may be delayed, incomplete, or inaccurate; do not rely on it for real trading decisions. Respect each exchange's terms of service and rate limits. See [SECURITY.md](SECURITY.md).