Freqtrade MCP

1# Freqtrade-MCP
2 
3An MCP server that integrates with the [Freqtrade](https://www.freqtrade.io/) cryptocurrency trading bot via its REST API, enabling seamless AI agent interaction for automated trading operation.
4 
5For more crypto-related MCP servers, see the [Kukapay MCP servers](https://github.com/kukapay/kukapay-mcp-servers).
6 
7![GitHub License](https://img.shields.io/github/license/kukapay/freqtrade-mcp)
8![Python Version](https://img.shields.io/badge/python-3.13+-blue)
9![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
10 
11## Installation
12 
13### Prerequisites
14- **Python 3.13+**: Ensure Python is installed on your system.
15- **Freqtrade**: A running Freqtrade instance with the REST API enabled (see [Freqtrade Docs](https://www.freqtrade.io/en/stable/rest-api/)).
16- **Git**: For cloning the repository.
17 
18### Steps
191. **Clone the Repository**:
20   ```bash
21   git clone https://github.com/kukapay/freqtrade-mcp.git
22   cd freqtrade-mcp
23   ```
24 
252. **Install Dependencies**:
26   Using `pip`:
27   ```bash
28   pip install freqtrade-client mcp[cli]
29   ```
30   Or with `uv` (optional):
31   ```bash
32   uv add freqtrade-client "mcp[cli]"
33   ```
34 
353. **Client Configuration**:
36 
37    ```
38    "mcpServers": { 
39      "freqtrade-mcp": { 
40        "command": "uv", 
41        "args": [ 
42          "--directory", "/your/path/to/freqtrade-mcp", 
43          "run", 
44          "__main__.py" 
45        ], 
46        "env": { 
47           "FREQTRADE_API_URL": "http://127.0.0.1:8080",
48           "FREQTRADE_USERNAME": "your_username",
49           "FREQTRADE_PASSWORD": "your_password"
50        } 
51      } 
52    }
53    ```
54    
554. **Freqtrade Configuration**:
56 
57    Enable the rest API by adding the api_server section to your configuration and setting api_server.enabled to true.
58 
59    Sample configuration:
60    ```
61        "api_server": {
62        "enabled": true,
63        "listen_ip_address": "127.0.0.1",
64        "listen_port": 8080,
65        "verbosity": "error",
66        "enable_openapi": false,
67        "jwt_secret_key": "somethingrandom",
68        "CORS_origins": [],
69        "username": "Freqtrader",
70        "password": "SuperSecret1!",
71        "ws_token": "sercet_Ws_t0ken"
72    },
73    ```
74 
75   Check the document [here](https://www.freqtrade.io/en/stable/rest-api/#configuration).
76 
77## Usage
78 
79### Available Tools
80The server exposes the following Freqtrade API endpoints as MCP tools:
81 
82| Tool                  | Description                          | Parameters                          |
83|-----------------------|--------------------------------------|-------------------------------------|
84| `fetch_market_data`   | Fetch OHLCV data for a pair          | `pair: str`, `timeframe: str`       |
85| `fetch_bot_status`    | Get open trade status                | None                                |
86| `fetch_profit`        | Get profit summary                   | None                                |
87| `fetch_balance`       | Get account balance                  | None                                |
88| `fetch_performance`   | Get performance metrics              | None                                |
89| `fetch_whitelist`     | Get whitelist of pairs               | None                                |
90| `fetch_blacklist`     | Get blacklist of pairs               | None                                |
91| `fetch_trades`        | Get trade history                    | None                                |
92| `fetch_config`        | Get bot configuration                | None                                |
93| `fetch_locks`         | Get trade locks                      | None                                |
94| `place_trade`         | Place a buy/sell trade               | `pair: str`, `side: str`, `stake_amount: float` |
95| `start_bot`           | Start the bot                        | None                                |
96| `stop_bot`            | Stop the bot                         | None                                |
97| `reload_config`       | Reload bot configuration             | None                                |
98| `add_blacklist`       | Add pair to blacklist                | `pair: str`                         |
99| `delete_blacklist`    | Remove pair from blacklist           | `pair: str`                         |
100| `delete_lock`         | Delete a trade lock                  | `lock_id: int`                      |
101 
102### Example Prompts
1031. **Fetch Market Data**:
104   - "Show me the hourly price data for BTC/USDT."
105   - "What’s the 5-minute chart for ETH/BTC like?"
106   - "Give me the latest candlestick data for XRP/USDT over the past hour."
107 
1082. **Fetch Bot Status**:
109   - "What’s the current status of my open trades?"
110   - "Are there any active trades right now?"
111   - "Tell me about the bot’s trading activity at the moment."
112 
1133. **Fetch Profit**:
114   - "How much profit have I made so far?"
115   - "What’s the total profit summary for the bot?"
116   - "Can you show me my trading gains?"
117 
1184. **Fetch Balance**:
119   - "What’s my account balance?"
120   - "How much money do I have in the trading account?"
121   - "Tell me the current balance of my Freqtrade wallet."
122 
1235. **Fetch Performance**:
124   - "How well has the bot been performing?"
125   - "What are the performance metrics for my trades?"
126   - "Show me the trading stats."
127 
1286. **Fetch Whitelist**:
129   - "Which pairs are on the whitelist?"
130   - "What trading pairs is the bot allowed to use?"
131   - "List the whitelisted pairs for me."
132 
1337. **Fetch Blacklist**:
134   - "Which pairs are blacklisted?"
135   - "What trading pairs are blocked right now?"
136   - "Tell me about the blacklist."
137 
1388. **Fetch Trades**:
139   - "What’s the history of my closed trades?"
140   - "Show me all the trades the bot has completed."
141   - "Can you list my past trades?"
142 
1439. **Fetch Config**:
144   - "What’s the current bot configuration?"
145   - "Show me the settings the bot is using."
146   - "Tell me about the Freqtrade config."
147 
14810. **Fetch Locks**:
149    - "Are there any trade locks active?"
150    - "What locks are currently in place?"
151    - "Show me the list of trading locks."
152 
15311. **Place Trade**:
154    - "Buy 0.01 BTC/USDT right now."
155    - "Sell 0.05 ETH/USDT immediately."
156    - "Place a buy order for 0.1 XRP/USDT."
157 
15812. **Start Bot**:
159    - "Start the trading bot."
160    - "Turn on the Freqtrade bot."
161    - "Get the bot running now."
162 
16313. **Stop Bot**:
164    - "Stop the trading bot."
165    - "Shut down the Freqtrade bot."
166    - "Pause the bot’s trading."
167 
16814. **Reload Config**:
169    - "Reload the bot’s configuration."
170    - "Update the bot settings."
171    - "Refresh the Freqtrade config."
172 
17315. **Add Blacklist**:
174    - "Blacklist ETH/USDT."
175    - "Add BTC/ETH to the blacklist."
176    - "Block trading for XRP/USDT."
177 
17816. **Delete Blacklist**:
179    - "Remove ETH/USDT from the blacklist."
180    - "Unblock BTC/ETH for trading."
181    - "Take XRP/USDT off the blacklist."
182 
18317. **Delete Lock**:
184    - "Delete the trade lock with ID 123."
185    - "Remove lock number 45."
186    - "Unlock the trade with ID 7."
187 
188## License
189 
190This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
191 
192