Overview

The Freqtrade MCP Server is a lightweight middleware designed to integrate Freqtrade bots into a scalable, observable, and programmatic trading infrastructure. It implements a Model Context Protocol (MCP) style API that standardizes how trading bots, strategies, and deployments are discovered, controlled, and monitored. This makes it easier to run multiple Freqtrade instances, coordinate strategy swaps, and surface bot telemetry to dashboards or automation pipelines.

For developers and ops teams, the MCP server removes much of the glue-code normally required to operate many Freqtrade containers. It exposes a consistent REST and (optionally) WebSocket surface for bot lifecycle actions (start/stop/restart), strategy management (upload/activate/test), and telemetry (metrics/logs), and is intended to be run inside orchestration environments (Docker, Kubernetes) or on standalone hosts.

Features

Standardized REST API to manage Freqtrade bot instances and strategies
WebSocket/streaming endpoints for real-time bot telemetry and trade events
Strategy upload, validation, and activation workflows
Support for multiple bots (local or remote Freqtrade instances)
Authentication token support and optional TLS for secure operations
Simple persistence for registered bots and strategy metadata (file or DB)
Docker-friendly and designed for orchestration (docker-compose / Kubernetes)
Basic health checks and metrics endpoint for monitoring

Installation / Configuration

These instructions show a typical installation using Docker. Adjust as needed for production (add TLS, database, secrets management).

Clone the repository:

git clone https://github.com/kukapay/freqtrade-mcp.git
cd freqtrade-mcp

Example docker-compose.yml (minimal):

version: "3.7"
services:
  mcp:
    image: kukapay/freqtrade-mcp:latest
    ports:
      - "8080:8080"        # API port
      - "9090:9090"        # optional metrics / websocket
    environment:
      - MCP_PORT=8080
      - AUTH_TOKEN=your-secret-token
      - STORAGE=local       # or "postgres"
      - FREQTRADE_HOME=/data/freqtrade
    volumes:
      - ./data:/data
      - ./strategies:/app/strategies

Start the MCP server:

docker-compose up -d

curl -X POST http://localhost:8080/api/v1/bots \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "bot-1",
    "api_url": "http://freqtrade-bot:8080",
    "api_key": "freqtrade-api-key"
  }'

Configuration notes:

AUTH_TOKEN (or similar) secures the MCP endpoints. Rotate and store securely.
STORAGE can be a simple filesystem for metadata or a proper RDBMS (Postgres) for scale.
Point MCP to the Freqtrade bot REST API endpoints; bots must expose their control APIs.

Available Resources

The MCP server typically exposes the following resources (endpoints are illustrative):

GET /api/v1/health — health check
GET /api/v1/bots — list registered bots
POST /api/v1/bots — register a new bot
GET /api/v1/bots/{id}/status — bot status and current pair/trades
POST /api/v1/bots/{id}/start — start bot
POST /api/v1/bots/{id}/stop — stop bot
POST /api/v1/strategies — upload and validate strategy file
POST /api/v1/bots/{id}/deploy-strategy — activate strategy on a bot
GET /api/v1/metrics — Prometheus-compatible metrics

Additional interfaces:

WebSocket /ws/events — real-time trade and order events
/logs/{bot_id} — accessible logs for troubleshooting

Authentication:

Bearer token header (Authorization: Bearer )
Optional mTLS or reverse-proxy TLS termination recommended in production

Use Cases

Centralized multi-bot orchestration
- Register many Freqtrade instances to a single MCP server.
- Use the MCP API to start/stop bots, rotate strategies at scheduled times, and coordinate cross-bot actions (e.g., portfolio rebalancing).
Continuous strategy deployment pipeline
- CI/CD pipeline uploads strategy files to the MCP server (POST /api/v1/strategies).
- MCP validates the strategy and triggers a staged deployment to a canary bot before rolling out to all bots.
Monitoring and alerting
- Expose metrics (/api/v1/metrics) to Prometheus and create alerts for lost connectivity, consistent drawdown, or failed trades.
- Subscribe to WebSocket event streams to forward important trades or errors into Slack/Discord or automation agents.
Backtesting and validation
- Use MCP to manage a fleet of backtesting bots: upload strategy sets and run backtests across different market datasets, collecting results centralised for comparison.

Tips for Developers

Start by running a single Freqtrade bot and registering it with the MCP server. Verify status and start/stop flows before scaling up.
Store secrets (API keys, AUTH_TOKEN) in a secrets manager or Kubernetes Secret; avoid plaintext in compose files.
Use the metrics endpoint and health checks to drive orchestration rules (auto-restart, scaling).
When deploying to production, place MCP behind a reverse proxy (NGINX) to add TLS, rate-limiting, and authentication layers.

Freqtrade MCP Server for Crypto Trading