freqtrade-mcp

What is Freqtrade-MCP?

Freqtrade-MCP is an MCP (Multi-Client Protocol) server designed to integrate with the Freqtrade cryptocurrency trading bot. It acts as a bridge, enabling AI agents to seamlessly interact with Freqtrade's REST API for automated trading operations.

How to use Freqtrade-MCP?

To use Freqtrade-MCP, you need Python 3.13+ and a running Freqtrade instance with its REST API enabled. After cloning the repository, install dependencies using pip or uv. Then, configure your MCP client to point to the freqtrade-mcp server and ensure your Freqtrade instance has its REST API enabled with the necessary authentication details.

Key Features of Freqtrade-MCP

• Seamless AI Agent Integration: Allows AI agents to interact with Freqtrade for automated trading.
• Comprehensive API Exposure: Exposes various Freqtrade API endpoints as MCP tools, including:
  • Fetching market data, bot status, profit, balance, performance, whitelists, blacklists, trades, config, and locks.
  • Placing buy/sell trades.
  • Starting/stopping the bot.
  • Reloading bot configuration.
  • Adding/deleting pairs from the blacklist.
  • Deleting trade locks.
• Easy Installation: Straightforward installation process with clear prerequisites and steps.
• MIT License: Open-source and freely usable under the MIT License.

Use Cases of Freqtrade-MCP

• Automated Cryptocurrency Trading: Develop and deploy AI agents to manage and execute trading strategies on Freqtrade.
• Bot Management: Programmatically control and monitor your Freqtrade bot's operations.
• Data Analysis: Easily fetch and analyze various trading data points from Freqtrade for strategy optimization.
• Custom Trading Interfaces: Build custom applications or interfaces that interact with Freqtrade through the MCP server.

Freqtrade-MCP FAQ

Q: What are the prerequisites for running Freqtrade-MCP? A: You need Python 3.13+ and a running Freqtrade instance with its REST API enabled.

Q: How do I install Freqtrade-MCP? A: Clone the repository, navigate to the directory, and install dependencies using pip install freqtrade-client mcp[cli].

Q: How do I configure Freqtrade-MCP with my Freqtrade instance? A: You need to configure your MCP client with the freqtrade-mcp server command and arguments, including environment variables for your Freqtrade API URL, username, and password. Additionally, ensure the REST API is enabled in your Freqtrade configuration.

Q: What Freqtrade API endpoints does Freqtrade-MCP expose? A: Freqtrade-MCP exposes a wide range of endpoints, including those for fetching market data, bot status, profit, balance, performance, whitelists, blacklists, trades, config, locks, and actions like placing trades, starting/stopping the bot, reloading config, and managing blacklists and locks.

Q: Can I use Freqtrade-MCP to automate my trading strategies? A: Yes, Freqtrade-MCP is specifically designed to enable AI agents to interact with Freqtrade for automated trading operations.

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:

Tool	Description	Parameters
fetch_market_data	Fetch OHLCV data for a pair	pair: str, timeframe: str
fetch_bot_status	Get open trade status	None
fetch_profit	Get profit summary	None
fetch_balance	Get account balance	None
fetch_performance	Get performance metrics	None
fetch_whitelist	Get whitelist of pairs	None
fetch_blacklist	Get blacklist of pairs	None
fetch_trades	Get trade history	None
fetch_config	Get bot configuration	None
fetch_locks	Get trade locks	None
place_trade	Place a buy/sell trade	pair: str, side: str, stake_amount: float
start_bot	Start the bot	None
stop_bot	Stop the bot	None
reload_config	Reload bot configuration	None
add_blacklist	Add pair to blacklist	pair: str
delete_blacklist	Remove pair from blacklist	pair: str
delete_lock	Delete a trade lock	lock_id: int

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.