convez.ai
MCP ServerFinanceiroAvançado
jayteelabs

Tempest Trading MCP

jayteelabs/tempest-trading-mcp

Análise técnica e backtesting para crypto via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP para análise de mercado e dados de criptmoedas. Fornece 21 ferramentas para indicadores técnicos, backtesting de estratégias, screening de ativos e análise de sentimento. NÃO executa trades — é puramente analítico.

Instalação

$npx convez-ai jayteelabs/tempest-trading-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
62%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
10

Casos de uso

  • Backtesting de estratégias (RSI, EMA, VWAP, Elliott Wave, Order Blocks)
  • Screening de ativos com detecção de breakout de sessão
  • Análise de sentimento combinado (Reddit + RSS)
  • Cálculo de indicadores técnicos e estrutura de mercado

Veredito

Ferramenta sólida para traders quantitativos que precisam integrar análise técnica avançada com Claude. A clareza sobre o escopo (análise, não execução) e os 21 tools bem documentados fazem dela um MCP maduro. Recomendado para quem quer automação de pesquisa e backtesting em crypto.

README

A tradução para o português deste README ainda está na fila.

tempest-trading-mcp

Market data & analytics MCP server — provides technical indicators, backtesting, screening, and sentiment analysis for crypto markets via the Model Context Protocol.

NOT a trading bot. No order execution, no position management, no trade placement.

tempest-trading-mcp capability overview

Capability overview: 21 public MCP tools spanning market data, indicators, screening, backtesting, market structure analysis, and sentiment overlays.

Public MCP Tools

The server exposes 21 public MCP tools:

Market Data

ToolDescription
fetch_tickerReal-time ticker price + 24h volume for a crypto symbol
fetch_klinesOHLCV klines with timeframe, limit, and exchange selection
fetch_orderbookOrder book depth for a symbol

Technical Indicators

ToolDescription
indicator_rsiRSI oscillator (0–100: <30 oversold, >70 overbought)

Backtesting

ToolDescription
backtest_pdh_sessionPDH/PDL + Session Levels strategy
backtest_rsiRSI Mean Reversion (long oversold, short overbought)
backtest_vwapVWAP Anchored trend-following with EMA confirmation
backtest_ema_stackMulti-EMA trend-following with risk management
backtest_order_blocksInstitutional order block detection with retest confirmation
backtest_elliot_waveElliott Wave counting with trend confirmation
compare_strategiesCompare 2+ strategies on a single OHLCV dataset, ranked by total_return descending, then sharpe_ratio descending, then strategy_id ascending

Screening

ToolDescription
screener_scanMulti-factor crypto screener with session breakout detection
session_breakout_scanSession breakout/proximity patterns against PDH/PDL
order_block_screener_scanActive order-block zones across 1h/1d and 4h/7d horizons

Analysis (Internal Engine)

ToolDescription
calculate_volume_profileVolume profile with POC, VAH, VAL, and shape classification
detect_order_blocksActive order-block zone detection (read-only)
calculate_fibonacciFibonacci retracement/extension levels
calculate_tpoTPO (Time-Price Opportunity) chart for a session
detect_elliot_waveElliott Wave pattern detection from OHLCV data
get_market_structureDeterministic market structure summary

Sentiment (Internal Engine)

ToolDescription
get_combined_sentiment_dashboardCombined Reddit + RSS sentiment (40% Reddit / 60% RSS weighted) with cross-signal detection

Note: Tools under "Internal Engine" categories represent analytical capabilities exposed via the MCP interface. The indicator breadth (30+ indicators) is an internal engine capability, not a direct 1:1 mapping to public MCP tool count.

For practical usage examples for all 21 public tools, see EXAMPLES.md.

Quick Start

# 1. Clone the repository
git clone https://github.com/jayteelabs/tempest-trading-mcp.git
cd tempest-trading-mcp

# 2. Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv pip install -e .

# 4. Configure environment (optional — defaults work out of the box)
cp .env.example .env

# 5. Run the MCP server (HTTP/SSE transport on :9001)
uv run python -m tempest_mcp.server

Configuration

Configuration is loaded from environment variables with the TEMPEST_ prefix:

VariableDescriptionDefault
TEMPEST_LOG_LEVELLogging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
TEMPEST_YF_CACHE_TTLYahoo Finance cache TTL (seconds)300
TEMPEST_CCXT_DEFAULT_EXCHANGEDefault exchange for real-time quotesbinance

Copy .env.example to .env and adjust as needed:

cp .env.example .env

No API keys required — the active data sources use public endpoints.

Note: TradingView is not an active market-data provider in the current architecture. Legacy TradingView compatibility code is retained only to avoid breaking older imports. Yahoo Finance remains the fallback/historical adapter; CCXT is the primary live-market-data path.

Deployment

Docker

# Build the image
sg docker -c "docker build -t tempest-trading-mcp ."

# Run the container with the MCP port published on host loopback
sg docker -c "docker run --rm -p 127.0.0.1:9001:9001 tempest-trading-mcp"

Notes:

  • The MCP server must bind to 0.0.0.0 inside the container for Docker port publishing to work.
  • Binding to 127.0.0.1 inside the container makes /sse reachable only from inside the container and breaks host-side MCP clients.
  • Publishing 127.0.0.1:9001:9001 on the host keeps the unauthenticated SSE + /messages surface local by default.
  • If you need remote access, expose intentionally behind a reverse proxy, Tailscale, firewall rules, or equivalent trusted-network controls.
  • The image includes a Dockerfile-level HEALTHCHECK that probes the SSE surface via a HEAD request to /sse.

Docker Compose

# First time: create the runtime env file used by docker-compose.yml
cp .env.example .env

# Build and start the service
sg docker -c "docker compose up -d --build"

# View logs
sg docker -c "docker compose logs -f"

# Stop the service
sg docker -c "docker compose down"

For fresh-clone validation without creating .env, override the runtime env-file path explicitly:

sg docker -c "TEMPEST_ENV_FILE=.env.example docker compose config"

The compose stack starts the MCP server on port 9001 with the HTTP/SSE transport (/sse for SSE connections, /messages for POST requests) and publishes it on host loopback by default (127.0.0.1:9001:9001).

Compose uses its default project-scoped container naming so repeated docker compose up runs do not collide with an older standalone docker run --name tempest-trading-mcp ... container.

Health check: The image includes a Dockerfile-level HEALTHCHECK that verifies the SSE endpoint is reachable via a HEAD request to http://localhost:9001/sse. The healthcheck exits 0 (healthy) when the endpoint exists (2xx-4xx response) and exits 1 (unhealthy) on 5xx or connection failure. Use sg docker -c "docker compose ps" to see the health status.

Note: The MCP server must bind to 0.0.0.0 inside the container for Docker port publishing to work. The Dockerfile is pre-configured to run the server on 0.0.0.0:9001, but the repo-owned Docker examples keep host publishing on loopback by default. Intentionally widen exposure only with compensating controls such as a reverse proxy, Tailscale, and/or firewall rules.

Architecture

For a detailed architecture deep-dive, see ARCHITECTURE.md.

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────────────┐
│ MCP Client  │────▶│  HTTP/SSE        │     │  Starlette + MCP Server    │
│ (optional)  │     │  /sse  /messages │────▶│  Tool Dispatch             │
└─────────────┘     └──────────────────┘     │  ├── Market Data           │
                                              │  ├── Backtest Engine       │
                                              │  ├── Screener              │
                                              │  ├── Analysis              │
                                              │  └── Sentiment             │
                                              └────────────┬──────────────┘
                                                           │
                                              ┌────────────▼──────────────┐
                                              │  Data Layer               │
                                              │  ├── CCXT (live, primary) │
                                              │  └── Yahoo Finance        │
                                              │      (historical fallback)│
                                              └────────────────────────────┘

Runtime boundary: MCP client(s) connect via HTTP/SSE to the Starlette/MCP server on port 9001. The server dispatches to internal engines (market data, backtest, screener, analysis, sentiment). External data dependencies are CCXT (live primary) and Yahoo Finance (historical fallback).

Kurisu and tempest-mesh are optional upstream callers in the broader ecosystem — they are not mandatory runtime dependencies of this repository.

Directory Structure


tempest-trading-mcp/
├── src/tempest_mcp/          # Main package
│   ├── __init__.py
│   ├── server.py             # MCP server entry point (HTTP/SSE on :9001)
│   ├── config.py             # Environment config loader (TEMPEST_* vars)
│   ├── logging_config.py     # Structured logging setup
│   ├── errors.py             # Error definitions
│   ├── time_utils.py         # Time utilities
│   ├── data/                 # Data layer
│   │   ├── yf_adapter.py     # Yahoo Finance adapter (historical fallback)
│   │   └── ccxt_adapter.py   # CCXT adapter (live primary, no keys)
│   ├── indicators/           # Technical indicator engine
│   │   ├── ta_wrapper.py     # ta-lib C extension wrapper (internal)
│   │   ├── session_levels.py # Asia/London/NY PDH/PDL
│   │   ├── trend/            # Trend indicators (EMA module today)
│   │   ├── momentum/         # RSI, MACD, Stochastic, CCI modules
│   │   ├── volatility/       # ATR and volatility modules
│   │   ├── volume/           # VWAP, TPO, and volume-profile modules
│   │   └── structure.py      # Fibonacci, Pivots, HH/HL
│   ├── backtest/             # Backtesting engine
│   ├── strategies/           # Strategy definitions
│   ├── screener/             # Multi-factor crypto screener
│   ├── sentiment/            # Sentiment analysis (Reddit + RSS)
│   ├── formatters/           # Output formatters (Discord)
│   ├── charting/             # mplfinance (debug only)
│   ├── models/               # Dataclass models
│   │   ├── backtest.py       # Backtest results
│   │   ├── indicator.py      # Indicator results
│   │   └── market.py         # Ticker, kline, orderbook
│   └── tools/                # MCP tool handlers
│       ├── __init__.py
│       ├── analysis_tools.py
│       ├── analytical_tools.py
│       ├── backtest_tools.py
│       ├── backtest_window.py
│       ├── indicator_tools.py
│       ├── market_tools.py
│       ├── screener_tools.py
│       └── sentiment_tools.py
├── tests/                    # Test suite
│   ├── conftest.py           # Pytest fixtures and integration markers
│   └── ...
├── docs/                     # Repository documentation
│   ├── backtest-mcp-tools-phase2.md
│   └── error-envelope-contract.md
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

Development

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests from this worktree's repo-local environment
# (avoids picking up a sibling editable checkout from a shared shell session)
uv run pytest

# Linting
uv run ruff check src/

# Format
uv run ruff format src/

Live-Data Integration Tests

# Run Phase 2 backtest live-data integration suite
# Fetches real BTCUSDT OHLCV via CCXT and validates strategy contracts
# across both 1h and 4h timeframes
uv run pytest --run-integration tests/test_phase2_backtest_live_integration.py -v

Error Codes

RangeCategory
1xxxValidation errors
3xxxData source errors (Yahoo Finance, CCXT)
5xxxIndicator/calculation errors
9xxxInternal/unexpected errors

Specific codes:

  • 1000 — Validation error
  • 1001 — Invalid symbol
  • 1002 — Invalid timeframe
  • 1003 — Invalid exchange
  • 1004 — Invalid parameter
  • 1005 — Missing parameter
  • 3000 — Data source error
  • 3001 — Yahoo Finance error
  • 3002 — CCXT error
  • 3003 — Data not found
  • 3004 — Rate limit error
  • 3005 — Network error
  • 5000 — Indicator error
  • 5001 — Insufficient data
  • 5002 — Calculation error
  • 9000 — Internal error
  • 9001 — Unexpected error

License

MIT License

Ver o original no GitHub

Bom para

Relacionados