{
  "markdown": "<!-- mcp-name: io.github.seungdori/tickscope-mcp -->\n\n<div align=\"center\">\n\n# Tickscope MCP\n\n**Real-time, free crypto market data for any AI agent — via MCP.**\n\n[![PyPI](https://img.shields.io/pypi/v/tickscope-mcp.svg)](https://pypi.org/project/tickscope-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/tickscope-mcp.svg)](https://pypi.org/project/tickscope-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![CI](https://github.com/seungdori/tickscope-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/seungdori/tickscope-mcp/actions/workflows/ci.yml)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-6E56CF.svg)](https://modelcontextprotocol.io)\n\n**English** · [한국어](README.ko.md) · [中文](README.zh-CN.md) · [日本語](README.ja.md)\n\n<!-- Live Claude Code walkthrough — see examples/RECORDING.md -->\n![Tickscope demo](docs/demo-agent.gif)\n\n</div>\n\nTickscope 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.\n\n> ⚠️ Educational/research tool. It does not provide financial, investment, or trading advice, and it does not guarantee data accuracy or timeliness.\n\n---\n\n## Contents\n\n- [Why](#why) · [See it run](#see-it-run) · [30-second install](#30-second-install)\n- [Supported exchanges](#supported-exchanges) · [Tools](#tools) · [Indicators](#indicators-73) · [Structure recognition](#structure-recognition)\n- [Example prompts](#example-prompts) · [Configuration](#configuration) · [Development](#development) · [Roadmap](#roadmap)\n\n## Why\n\nTrading 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.\n\n## See it run\n\n```bash\nuv run examples/demo.py            # live BTC/USDT walkthrough (no API keys)\nuv run examples/demo.py ETH/USDT 4h\n```\n\nA 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.\n\n## 30-second install\n\n```bash\nuvx tickscope-mcp\n```\n\nRegister it with your client (Claude Code example, [`examples/claude_code_config.json`](examples/claude_code_config.json)):\n\n```json\n{\n  \"mcpServers\": {\n    \"tickscope\": {\n      \"command\": \"uvx\",\n      \"args\": [\"tickscope-mcp\"],\n      \"env\": {\n        \"TICKSCOPE_EXCHANGES\": \"binance,bybit,okx\",\n        \"TICKSCOPE_DEFAULT_EXCHANGE\": \"binance\"\n      }\n    }\n  }\n}\n```\n\nCursor, Codex and Gemini CLI use the same `command`/`args`/`env` shape in their respective MCP config files.\n\n## Supported exchanges\n\n| Exchange | REST | WebSocket |\n|---|:---:|:---:|\n| Binance | ✅ | ✅ |\n| Bybit | ✅ | ✅ |\n| OKX | ✅ | ✅ |\n\nAny [ccxt](https://github.com/ccxt/ccxt)-supported exchange can be enabled via `TICKSCOPE_EXCHANGES`. Public data only — no keys required.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `list_exchanges` | Configured exchanges + default |\n| `list_symbols` | Tradable symbols (filter by quote/search) |\n| `get_ticker` | Current price snapshot (primary quote tool) |\n| `get_recent_trades` | Recent executed trades from the live buffer |\n| `get_ohlcv` | Historical candles (DuckDB-cached) |\n| `get_orderbook` | Order book snapshot + spread |\n| `compute_indicators` | 73 indicators (RSI/MACD/Supertrend/WaveTrend/Squeeze/…) with derived signals |\n| `detect_divergence` | Regular/hidden bullish & bearish divergence (price vs oscillator) |\n| `detect_cross` | Pine-style `ta.crossover`/`ta.crossunder` between any two series |\n| `detect_patterns` | Candlestick patterns (engulfing, hammer, stars, …) with bias |\n| `analyze_structure` | Market structure: swings, trend, BOS / CHoCH |\n| `find_support_resistance` | Clustered support/resistance zones from pivots |\n| `deep_analyze` | Multi-timeframe read: trend confluence + market-state context + historical signal performance, with a synthesized verdict |\n| `screen_market` | Scan many symbols by indicator/price filters |\n| `get_aggregated_price` | Volume-weighted price + cross-exchange spread (arbitrage) |\n| `get_funding_rate` | Perpetual funding rate |\n| `watch_symbol` | Pre-warm a live subscription (optional) |\n| `get_watched_symbols` | Active subscriptions + buffer state |\n| `server_status` | Health / diagnostics |\n\nEvery market-data response includes `source` (`websocket`|`rest`), `age_ms`, and `timestamp` so the freshness is always provable.\n\n### Indicators (73)\n\n- **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`\n- **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`\n- **Volatility:** `atr natr stdev hv chop ulcer massindex`\n- **Volume:** `obv adl cmf chaikinosc eom fi pvt vo klinger`\n- **Trend:** `adx dmi aroon vortex`\n- **Structure:** `heikinashi pivots`\n\nSpecs 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.\n\n### Structure recognition\n\nOn 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.\n\n### Deep analysis\n\n`deep_analyze` answers a question about a symbol in one call, instead of making the agent chain a dozen tools. It returns:\n\n- **Multi-timeframe trend confluence** — the same symbol read across a 1d/4h/1h ladder, with whether the timeframes agree or conflict.\n- **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.\n- **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.\n- **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.\n\n`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.\n\n### Resources\n\nSupporting clients can also read live state as MCP resources: `tickscope://status`, `tickscope://watched`, and the template `tickscope://ticker/{exchange}/{symbol}`.\n\n## Example prompts\n\n- \"What's BTC/USDT trading at on Binance right now, and the 24h change?\"\n- \"Should I care about this SOL/USDT setup? Do a deep, multi-timeframe read.\"\n- \"Is there an RSI divergence on BTC/USDT 4h — and how has that signal performed on this pair before?\"\n- \"Screen the top 50 USDT pairs by volume for ones with RSI below 30.\"\n- \"Map the key support/resistance on ETH/USDT 4h and tell me if the structure just broke (BOS/CHoCH).\"\n- \"What's the perpetual funding rate for BTC on Bybit right now — is it overheated?\"\n- \"Compare BTC/USDT across Binance, Bybit and OKX and show the arbitrage spread.\"\n\nSee [`examples/demo_prompts.md`](examples/demo_prompts.md) for a fuller recipe book (deep analysis, signal backtests, screening, monitoring, strategy checks).\n\n## Configuration\n\nAll settings are environment variables (see [`.env.example`](.env.example)):\n\n| Variable | Default | Description |\n|---|---|---|\n| `TICKSCOPE_EXCHANGES` | `binance,bybit,okx` | Enabled exchanges (comma-separated) |\n| `TICKSCOPE_DEFAULT_EXCHANGE` | `binance` | Default when `exchange` is omitted |\n| `TICKSCOPE_MAX_WATCHED_SYMBOLS` | `25` | Max concurrent WS subscriptions (LRU evicted) |\n| `TICKSCOPE_RING_BUFFER_SIZE` | `1000` | Per-symbol trade buffer size |\n| `TICKSCOPE_OHLCV_CACHE_PATH` | `~/.tickscope/ohlcv.duckdb` | DuckDB cache file |\n| `TICKSCOPE_OHLCV_CACHE_TTL_S` | `60` | Freshness window for the newest candle |\n| `TICKSCOPE_REST_RETRIES` | `3` | Retry attempts for transient REST errors (rate limit / network) |\n| `TICKSCOPE_SCREEN_CONCURRENCY` | `5` | Max concurrent symbols during screening/aggregation |\n| `TICKSCOPE_TRANSPORT` | `stdio` | `stdio` or `http` |\n| `TICKSCOPE_LOG_LEVEL` | `INFO` | Log level |\n\n## Development\n\n```bash\nuv venv && uv pip install -e \".[dev]\"\npytest                # ~100 unit + MCP-integration tests (live excluded)\npytest -m live        # live exchange tests (Binance/Bybit/OKX, run locally)\nruff check . && mypy  # lint + type gates\n```\n\nTests 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.\n\n## Roadmap\n\n- [x] Pine Script-style indicator mapping (`ta.rsi`, `ta.crossover`, …)\n- [x] 73 indicators + candlestick patterns + market structure (BOS/CHoCH)\n- [x] Multi-exchange aggregation (weighted price / spread)\n- [x] MCP resource push for watched symbols\n- [ ] Anchored / session VWAP\n- [ ] More exchanges (Kraken, Bitget, Gate, …)\n- [ ] Agent Skill (`SKILL.md`) wrapper\n\n## Contributing\n\nIssues 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).\n\n## License\n\n[MIT](LICENSE) © Tickscope contributors.\n\n## Disclaimer\n\nThis 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).\n",
  "bytes": 11736,
  "sha": "ff18b8aa5cea1be04572286a886e37e85d086074ca500c2737d0d9859de39610",
  "repo_slug": "seungdori/tickscope-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_seungdori_tickscope_mcp_9b4be6a7/readme"
}