CCXT MCP Server

1# CCXT MCP Server
2 
3<img src="assets/ccxt-logo.png" alt="CCXT Logo" width="100" height="100"/>
4 
5![Version](https://img.shields.io/badge/version-1.2.1-blue.svg)
6[![MCP Standard](https://img.shields.io/badge/MCP-Standard-green.svg)](https://www.modelcontextprotocol.org/)
7[![CCXT](https://img.shields.io/badge/CCXT-4.0.0-orange.svg)](https://github.com/ccxt/ccxt)
8[![smithery badge](https://smithery.ai/badge/@doggybee/mcp-server-ccxt)](https://smithery.ai/server/@doggybee/mcp-server-ccxt)
9 
10High-performance cryptocurrency exchange integration using MCP (Model Context Protocol) and CCXT.
11 
12## Features
13 
14- 🚀 **Exchange Support**: Connects to 20+ cryptocurrency exchanges
15- 🔃 **Market Types**: Supports spot, futures, swap markets and more
16- 🔧 **Proxy Configuration**: Options for accessing exchanges through proxies
17- 📊 **Fast & Reliable**: Optimized caching and rate limiting
18- 🌐 **MCP Standard**: Compatible with LLMs like Claude and GPT via MCP
19 
20## CCXT MCP Server Integration Architecture
21 
22![CCXT MCP Server Integration Architecture](docs/images/mcp-integration.svg)
23 
24The CCXT MCP Server connects language models to cryptocurrency exchanges through the Model Context Protocol. It serves as a bridge that allows LLMs to access real-time market data and execute trading operations across multiple exchanges through a unified API.
25 
26The architecture includes:
27- LLM clients (Claude and other MCP-compatible models) that send requests
28- The Model Context Protocol (MCP) that standardizes communication
29- The CCXT MCP Server that processes requests and manages exchange interactions
30- The CCXT Library that provides unified access to exchange APIs
31- Connections to multiple cryptocurrency exchanges
32 
33## CCXT MCP Server Code Architecture
34 
35![CCXT MCP Server Code Architecture](docs/images/code-architecture.svg)
36 
37The server is organized into three main modules for better maintainability and extensibility:
38 
39- **Exchange**: Manages exchange instances, credentials, and symbol validation
40- **Utils**: Provides caching, rate limiting, and logging functionality 
41- **Tools**: Implements MCP tools and resources for exchange interaction
42 
43## Quick Start
44 
45### Installing via Smithery
46 
47To install mcp-server-ccxt for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@doggybee/mcp-server-ccxt):
48 
49```bash
50npx -y @smithery/cli install @doggybee/mcp-server-ccxt --client claude
51```
52 
53### NPM Package (Recommended)
54 
55You can install CCXT MCP Server from npm:
56 
57```bash
58# Install globally
59npm install -g @mcpfun/mcp-server-ccxt
60 
61# Start the server
62mcp-server-ccxt
63```
64 
65Or run directly:
66 
67```bash
68npx @mcpfun/mcp-server-ccxt
69```
70 
71### Manual Installation
72 
73Alternatively, you can clone and build the repository:
74 
75```bash
76# Clone the repository
77git clone https://github.com/doggybee/mcp-server-ccxt.git
78cd mcp-server-ccxt
79 
80# Install dependencies
81npm install
82 
83# Build the server
84npm run build
85 
86# Start the server
87npm start
88```
89 
90## Configuration
91 
921. Create an environment file
93   ```bash
94   cp .env.example .env
95   ```
96 
972. Edit the `.env` file to add your exchange API keys
98   ```
99   # Default exchange (optional)
100   DEFAULT_EXCHANGE=binance
101   
102   # Default market type (optional)
103   DEFAULT_MARKET_TYPE=spot 
104   
105   # API credentials (optional)
106   BINANCE_API_KEY=your_api_key
107   BINANCE_SECRET=your_api_secret
108   # For exchanges requiring passphrase (e.g., KuCoin)
109   KUCOIN_API_KEY=your_kucoin_api_key
110   KUCOIN_SECRET=your_kucoin_secret
111   KUCOIN_PASSPHRASE=your_kucoin_passphrase
112   
113   # Proxy configuration (optional)
114   USE_PROXY=false
115   PROXY_URL=http://username:password@your-proxy-server:port
116   # Legacy format (still supported but recommended to use the integrated URL format above)
117   # PROXY_USERNAME=
118   # PROXY_PASSWORD=
119   ```
120 
121## Usage
122 
123> **Note**: If you encounter any issues with MCP communication, please see the [Troubleshooting Guide](docs/troubleshooting.md) for solutions.
124 
125### Running the Server
126 
127Start the server:
128 
129```bash
130# If installed globally via npm
131mcp-server-ccxt
132 
133# If installed manually
134npm start
135```
136 
137### Using with Claude for Desktop
138 
1391. Add the server to your `claude_desktop_config.json`:
140 
141If installed via npm (globally):
142```json
143{
144  "mcpServers": {
145    "ccxt": {
146      "command": "mcp-server-ccxt"
147    }
148  }
149}
150```
151 
152If installed manually:
153```json
154{
155  "mcpServers": {
156    "ccxt": {
157      "command": "node",
158      "args": [
159        "/path/to/mcp-server-ccxt/build/index.js"
160      ]
161    }
162  }
163}
164```
165 
1662. Restart Claude for Desktop
167 
168### Using as a Module in Another Project
169 
170You can also use this package as a module in your own Node.js projects:
171 
172```javascript
173// Import the CCXT MCP Server
174import '@mcpfun/mcp-server-ccxt';
175 
176// The server starts automatically when imported
177// You can configure it through environment variables
178```
179 
180## Example Queries
181 
182Here are some example queries you can use with the MCP server:
183 
184- "What's the current price of Bitcoin on Binance?"
185- "Show me the order book for ETH/USDT on Coinbase"
186- "Get the 1-hour OHLCV data for BTC/USDT on Binance for the last 24 candles"
187- "Compare the price of SOL/USDT across different exchanges"
188- "What's my current balance on Binance?" (requires API keys)
189- "Place a market buy order for 0.1 ETH on Kraken" (requires API keys)
190 
191## Available Tools
192 
193### Public API Tools
194 
195- `list-exchanges`: List all available cryptocurrency exchanges
196- `get-ticker`: Get current ticker information for a trading pair
197- `batch-get-tickers`: Get ticker information for multiple trading pairs at once
198- `get-orderbook` / `get-order-book`: Get market order book for a trading pair
199- `get-ohlcv`: Get OHLCV candlestick data for a trading pair
200- `get-trades`: Get recent trades for a trading pair
201- `get-markets`: Get all available markets for an exchange
202- `get-exchange-info`: Get exchange information and status
203- `get-leverage-tiers`: Get futures leverage tiers
204- `get-funding-rates`: Get current funding rates
205- `get-positions`: Get open positions information
206- `get-open-orders`: Get all open orders
207- `get-order-history`: Get order history
208 
209### Private API Tools (requires API keys)
210 
211- `account-balance`: Get your account balance from a crypto exchange
212- `place-market-order`: Place a market order on an exchange
213- `place-limit-order`: Place a limit order on an exchange
214- `cancel-order`: Cancel an existing order
215- `cancel-all-orders`: Cancel all open orders
216- `set-leverage`: Set leverage for futures
217- `set-margin-mode`: Set margin mode for futures
218- `place-futures-market-order`: Place futures market orders
219- `place-futures-limit-order`: Place futures limit orders
220- `transfer-funds`: Transfer funds between accounts (e.g., spot to futures)
221 
222### Configuration & Utility Tools
223 
224- `cache-stats`: Get CCXT cache statistics
225- `clear-cache`: Clear CCXT cache
226- `set-log-level`: Set logging level
227- `get-proxy-config`: Get proxy settings
228- `set-proxy-config`: Configure proxy settings
229- `set-market-type`: Set default market type
230- `set-default-exchange`: Change the default exchange
231- `system-info`: Get system and environment information
232 
233## Performance Optimizations
234 
235MCP-CCXT includes several optimizations to ensure high performance:
236 
2371. **LRU Caching System**:
238   - Different TTLs for different types of data
239   - Ticker data: 10 seconds
240   - Order book data: 5 seconds
241   - Market data: 1 hour
242 
2432. **Adaptive Rate Limiting**:
244   - Automatically adjusts request rates based on exchange responses
245   - Implements exponential backoff for errors
246   - Manages concurrent requests per exchange
247 
2483. **Exchange Connection Management**:
249   - Efficient initialization of exchange instances
250   - Proper error handling and retries
251 
252## Security Best Practices
253 
254### API Key Security
255 
2561. **Create Dedicated API Keys**:
257   - Create separate API keys for different applications/purposes
258   - Never reuse API keys across different services or applications
259 
2602. **Limit API Key Permissions**:
261   - Enable only the permissions you need (e.g., read-only for market data)
262   - Disable withdrawal permissions if you only need trading functionality
263   - Use IP whitelisting when available to restrict access to known IPs
264 
2653. **Secure Storage**:
266   - Never commit API keys to version control systems
267   - Store API keys in environment variables or a secure vault
268   - Use `.env` files that are excluded from git via `.gitignore`
269 
270## Risk Disclaimer
271 
272This software is provided for informational purposes only. Using this software to interact with cryptocurrency exchanges involves significant risks:
273 
274- **Financial Risk**: Cryptocurrency trading involves risk of loss
275- **API Security**: Ensure your API keys have appropriate permission limits
276- **No Investment Advice**: This tool does not provide investment advice
277- **No Warranty**: The software is provided "as is" without warranty of any kind
278 
279## License
280 
281This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
282 
283## Copyright and Attribution
284 
285This project uses the CCXT library (https://github.com/ccxt/ccxt), which is:
286 
287```
288Copyright (c) 2016-2024 CCXT developers
289```
290 
291CCXT is released under the MIT License, which is included below:
292 
293```
294Permission is hereby granted, free of charge, to any person obtaining a copy
295of this software and associated documentation files (the "Software"), to deal
296in the Software without restriction, including without limitation the rights
297to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
298copies of the Software, and to permit persons to whom the Software is
299furnished to do so, subject to the following conditions:
300 
301The above copyright notice and this permission notice shall be included in all
302copies or substantial portions of the Software.
303 
304THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
305IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
306FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
307AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
308LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
309OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
310SOFTWARE.
311```
312 
313---
314 
315For issues, feature requests, or contributions, please visit [the GitHub repository](https://github.com/doggybee/mcp-server-ccxt).