Freqtrade-MCP

An MCP server that integrates with the Freqtrade cryptocurrency trading bot via its REST API, enabling seamless AI agent interaction for automated trading operation.

Installation

Prerequisites

• Python 3.13+: Ensure Python is installed on your system.
• Freqtrade: A running Freqtrade instance with the REST API enabled (see Freqtrade Docs).
• Git: For cloning the repository.

Steps

1. Clone the Repository:
   git clone https://github.com/kukapay/freqtrade-mcp.git cd freqtrade-mcp
2. Install Dependencies: Using pip:
   pip install freqtrade-client mcp[cli]
   Or with uv (optional):
   uv add freqtrade-client "mcp[cli]"
3. Client Configuration:
   "mcpServers": { "freqtrade-mcp": { "command": "uv", "args": [ "--directory", "/your/path/to/freqtrade-mcp", "run", "__main__.py" ], "env": { "FREQTRADE_API_URL": "http://127.0.0.1:8080", "FREQTRADE_USERNAME": "your_username", "FREQTRADE_PASSWORD": "your_password" } } }
4. Freqtrade Configuration: Enable the rest API by adding the api_server section to your configuration and setting api_server.enabled to true. Sample configuration:
   "api_server": { "enabled": true, "listen_ip_address": "127.0.0.1", "listen_port": 8080, "verbosity": "error", "enable_openapi": false, "jwt_secret_key": "somethingrandom", "CORS_origins": [], "username": "Freqtrader", "password": "SuperSecret1!", "ws_token": "sercet_Ws_t0ken" },
   Check the document here.

Usage

Available Tools

The server exposes the following Freqtrade API endpoints as MCP tools:

Example Prompts

1. Fetch Market Data:
   • "Show me the hourly price data for BTC/USDT."
   • "What’s the 5-minute chart for ETH/BTC like?"
   • "Give me the latest candlestick data for XRP/USDT over the past hour."
2. Fetch Bot Status:
   • "What’s the current status of my open trades?"
   • "Are there any active trades right now?"
   • "Tell me about the bot’s trading activity at the moment."
3. Fetch Profit:
   • "How much profit have I made so far?"
   • "What’s the total profit summary for the bot?"
   • "Can you show me my trading gains?"
4. Fetch Balance:
   • "What’s my account balance?"
   • "How much money do I have in the trading account?"
   • "Tell me the current balance of my Freqtrade wallet."
5. Fetch Performance:
   • "How well has the bot been performing?"
   • "What are the performance metrics for my trades?"
   • "Show me the trading stats."
6. Fetch Whitelist:
   • "Which pairs are on the whitelist?"
   • "What trading pairs is the bot allowed to use?"
   • "List the whitelisted pairs for me."
7. Fetch Blacklist:
   • "Which pairs are blacklisted?"
   • "What trading pairs are blocked right now?"
   • "Tell me about the blacklist."
8. Fetch Trades:
   • "What’s the history of my closed trades?"
   • "Show me all the trades the bot has completed."
   • "Can you list my past trades?"
9. Fetch Config:
   • "What’s the current bot configuration?"
   • "Show me the settings the bot is using."
   • "Tell me about the Freqtrade config."
10. Fetch Locks:
    • "Are there any trade locks active?"
    • "What locks are currently in place?"
    • "Show me the list of trading locks."
11. Place Trade:
    • "Buy 0.01 BTC/USDT right now."
    • "Sell 0.05 ETH/USDT immediately."
    • "Place a buy order for 0.1 XRP/USDT."
12. Start Bot:
    • "Start the trading bot."
    • "Turn on the Freqtrade bot."
    • "Get the bot running now."
13. Stop Bot:
    • "Stop the trading bot."
    • "Shut down the Freqtrade bot."
    • "Pause the bot’s trading."
14. Reload Config:
    • "Reload the bot’s configuration."
    • "Update the bot settings."
    • "Refresh the Freqtrade config."
15. Add Blacklist:
    • "Blacklist ETH/USDT."
    • "Add BTC/ETH to the blacklist."
    • "Block trading for XRP/USDT."
16. Delete Blacklist:
    • "Remove ETH/USDT from the blacklist."
    • "Unblock BTC/ETH for trading."
    • "Take XRP/USDT off the blacklist."
17. Delete Lock:
    • "Delete the trade lock with ID 123."
    • "Remove lock number 45."
    • "Unlock the trade with ID 7."

License

This project is licensed under the MIT License. See the LICENSE file for details.