Freqtrade-Gateway-Agent

An intermediary service layer that interfaces with the Freqtrade trading application utilizing its built-in Representational State Transfer (REST) Application Programming Interface (API), thereby facilitating smooth integration for sophisticated automated trading operations managed by AI entities.

Setup Procedure

Prerequisites

• Runtime Environment (Python 3.13 or newer): Mandatory installation of a compatible Python interpreter.
• Freqtrade Instance: A persistently operating Freqtrade deployment where the web service (REST API) functionality has been explicitly activated (refer to the official Freqtrade Documentation).
• Version Control (Git): Necessary for cloning the source repository structure.

Deployment Steps

1. Repository Acquisition: bash git clone https://github.com/kukapay/freqtrade-mcp.git cd freqtrade-mcp

2. Dependency Resolution: Using the standard package installer (pip): bash pip install freqtrade-client mcp[cli]

Alternatively, employing the uv utility (optional optimization): bash uv add freqtrade-client "mcp[cli]"

1. Client Configuration File Modification:

   In the relevant configuration scope, incorporate the following structure:

   "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" } } }

2. Freqtrade Service Configuration Adjustment:

   Ensure the REST API endpoint is activated by modifying the primary Freqtrade configuration file, specifically enabling the api_server block and setting its activation flag to true.

   Exemplary configuration snippet:

   "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"
   

   },

Consult the Freqtrade documentation for detailed API settings here.

Operational Use Cases

Exposed Functionalities (Tools)

The gateway exposes the following capabilities, mapped directly to Freqtrade's web interface endpoints, available as MCP operational units:

Tool Name	Purpose	Input Arguments Required
fetch_market_data	Retrieve historical candlestick data for a symbol	pair: str, timeframe: str
fetch_bot_status	Query current open trade positions	None
fetch_profit	Obtain overall return summary	None
fetch_balance	Access current asset holdings	None
fetch_performance	Retrieve analytical trading metrics	None
fetch_whitelist	List permitted trading instruments	None
fetch_blacklist	List prohibited trading instruments	None
fetch_trades	Access finalized transaction records	None
fetch_config	View active system settings	None
fetch_locks	Retrieve active trade restrictions	None
place_trade	Submit a directional market order	pair: str, side: str, stake_amount: float
start_bot	Initiate the automated trading engine	None
stop_bot	Halt the automated trading engine	None
reload_config	Force an update to the running configuration	None
add_blacklist	Add a symbol to the exclusion list	pair: str
delete_blacklist	Remove a symbol from the exclusion list	pair: str
delete_lock	Clear a specific trade restriction	lock_id: int

Sample Agent Directives

1. Market Data Retrieval:
2. "Provide the hourly Open, High, Low, Close, Volume data for BTC/USDT."
3. "Examine the 5-minute chart series for ETH paired against BTC."

4. "Furnish the most recent OHLCV sequence for XRP/USDT across the sixty-minute interval."

5. Bot State Inquiry:

6. "Report on the standing positions currently held by the system."
7. "Are there any trades actively being managed at this moment?"

8. "Summarize the execution activity of the bot presently."

9. Financial Outcome Review:

10. "What is the cumulative realized profit to date?"
11. "Display the aggregated profit statistics for all operations."

12. "Show me the trading gains realized thus far."

13. Account Liquidity Check:

14. "What are the current holdings in the associated account?"
15. "How much deployable capital resides in the exchange wallet?"

16. "Detail the current balance status for the Freqtrade participant."

17. Performance Assessment:

18. "How effective has the bot's performance been over the tracked period?"
19. "What are the quantitative performance indicators for executed trades?"

20. "Present the statistical trading outcomes."

21. Permitted Pairs Listing:

22. "Which trading instruments are currently designated as whitelisted?"
23. "What assets is the trading mechanism authorized to interact with?"

24. "Enumerate the currently whitelisted asset pairings."

25. Restricted Pairs Listing:

26. "Which trading pairs are currently subject to restriction?"
27. "Identify all assets that are currently blocked from trading."

28. "Provide a catalog of blacklisted instruments."

29. Trade History Retrieval:

30. "Display the chronological record of concluded transactions."
31. "List every trade operation that has reached closure."

32. "Can you furnish an archive of historical trade events?"

33. System Settings Inspection:

34. "What is the present configuration governing the bot's behavior?"
35. "Display the operational parameters currently loaded."

36. "Detail the current setup parameters of the Freqtrade instance."

37. Trade Restriction Review:

    • "Are there any extant trade reservation mechanisms active?"
    • "What specific trading constraints are presently enforced?"
    • "Output the inventory of active trading constraints."

38. Order Placement Command:

    • "Execute a purchase order for 0.01 units of BTC/USDT immediately."
    • "Submit a sell instruction for 0.05 units of ETH/USDT at the current market rate."
    • "Initiate a buy transaction request targeting 0.1 XRP/USDT."

39. Engine Activation:

    • "Initiate the trading automaton."
    • "Commence operations for the Freqtrade component."
    • "Set the bot into an active, trading state forthwith."

40. Engine Deactivation:

    • "Halt the processes of the trading automaton."
    • "Execute a controlled shutdown of the Freqtrade service."
    • "Temporarily suspend all automated trading activities."

41. Configuration Refresh:

    • "Apply the latest configuration file changes to the running service."
    • "Update the bot's internal operational parameters."
    • "Re-read and implement the Freqtrade operational settings."

42. Blacklist Addition:

    • "Prohibit trading activity for the ETH/USDT pair."
    • "Incorporate BTC/ETH into the list of prohibited assets."
    • "Enforce a trading block on XRP/USDT."

43. Blacklist Removal:

    • "Remove the ETH/USDT pairing from the restriction roster."
    • "Lift the trading prohibition currently placed on BTC/ETH."
    • "Deregister XRP/USDT from the list of blocked instruments."

44. Lock Elimination:

    • "Disengage the trade lock identified by identifier 123."
    • "Expunge the constraint associated with lock reference 45."
    • "Release the trading constraint labeled as ID 7."

Licensing Information

This software project is distributed under the terms of the MIT License. Comprehensive details are available in the accompanying LICENSE file.