Skip to content
Back to search

ccxt-mcp

CCXT MCP Server bridges the gap between AI models and cryptocurrency trading by providing a standardized interface through the Model Context Protocol. Created to empower automated trading strategies, this tool allows AI assistants like Claude and GPT to directly interact with over 100 cryptocurrency exchanges without requiring users to write comple

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lazy-dinosaur--ccxt-mcp/badge.svg)](/listings/lazy-dinosaur--ccxt-mcp)

HTML

<a href="/listings/lazy-dinosaur--ccxt-mcp"><img src="/api/listings/lazy-dinosaur--ccxt-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install the package globally
npm install -g @lazydino/ccxt-mcp

# Run with default settings
ccxt-mcp

# or run without installation
npx @lazydino/ccxt-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 427 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # CCXT MCP Server
  2. [![npm version](https://img.shields.io/npm/v/@lazydino/ccxt-mcp.svg)](https://www.npmjs.com/package/@lazydino/ccxt-mcp)
  3. [![npm downloads](https://img.shields.io/npm/dm/@lazydino/ccxt-mcp.svg)](https://www.npmjs.com/package/@lazydino/ccxt-mcp)
  4. [![GitHub stars](https://img.shields.io/github/stars/lazy-dinosaur/ccxt-mcp.svg)](https://github.com/lazy-dinosaur/ccxt-mcp/stargazers)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [한국어 버전(Korean version)](README.ko.md)
  7. CCXT MCP Server is a server that allows AI models to interact with cryptocurrency exchange APIs through the [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-cookbook/tree/main/model-context-protocol). This server uses the [CCXT library](https://github.com/ccxt/ccxt) to provide access to more than 100 cryptocurrency exchanges and their trading capabilities.
  8. ## 🚀 Quick Start
  9. ```bash
  10. # Install the package globally
  11. npm install -g @lazydino/ccxt-mcp
  12. # Run with default settings
  13. ccxt-mcp
  14. # or run without installation
  15. npx @lazydino/ccxt-mcp
  16. ```
  17. ## Installation and Usage
  18. ### Global Installation
  19. ```bash
  20. # Install the package globally
  21. npm install -g @lazydino/ccxt-mcp
  22. ```
  23. ### Running with npx
  24. You can run it directly without installation:
  25. ```bash
  26. # Using default settings
  27. npx @lazydino/ccxt-mcp
  28. # Using custom configuration file
  29. npx @lazydino/ccxt-mcp --config /path/to/config.json
  30. ```
  31. View help:
  32. ```bash
  33. npx @lazydino/ccxt-mcp --help
  34. ```
  35. ## Configuration
  36. ### Registering the MCP Server in Claude Desktop
  37. 1. **Open Claude Desktop Settings**:
  38. - Go to the Settings menu in the Claude Desktop app
  39. - Find the "MCP Servers" section
  40. 2. **Add a New MCP Server**:
  41. - Click the "Add Server" button
  42. - Server name: `ccxt-mcp`
  43. - Command: `npx @lazydino/ccxt-mcp`
  44. - Additional arguments (optional): `--config /path/to/config.json`
  45. 3. **Save and Test the Server**:
  46. - Save the settings
  47. - Test the connection with the "Test Connection" button
  48. ### Configuration Methods - Two Options
  49. #### Option 1: Include Account Information Directly in Claude Desktop Settings (Basic Method)
  50. This method includes CCXT account information directly in the Claude Desktop settings file (claude_desktop_config.json):
  51. ```json
  52. {
  53. "mcpServers": {
  54. "ccxt-mcp": {
  55. "command": "npx",
  56. "args": ["-y", "@lazydino/ccxt-mcp"],
  57. "mcpBearerToken": "YOUR_MCP_TOKEN",
  58. "accounts": [
  59. {
  60. "name": "bybit_main",
  61. "exchangeId": "bybit",
  62. "apiKey": "YOUR_API_KEY",
  63. "secret": "YOUR_SECRET_KEY",
  64. "defaultType": "spot"
  65. },
  66. {
  67. "name": "bybit_futures",
  68. "exchangeId": "bybit",
  69. "apiKey": "YOUR_API_KEY",
  70. "secret": "YOUR_SECRET_KEY",
  71. "defaultType": "swap"
  72. }
  73. ]
  74. }
  75. }
  76. }
  77. ```
  78. Using this method, you don't need a separate configuration file. All settings are integrated into the Claude Desktop configuration file.
  79. #### Option 2: Using a Separate Configuration File (Advanced Method)
  80. To separate account information into a separate configuration file, set up as follows:
  81. 1. **Create a Separate Configuration File** (e.g., `ccxt-config.json`):
  82. ```json
  83. {
  84. "mcpBearerToken": "YOUR_MCP_TOKEN",
  85. "accounts": [
  86. {
  87. "name": "bybit_main",
  88. "exchangeId": "bybit",
  89. "apiKey": "YOUR_API_KEY",
  90. "secret": "YOUR_SECRET_KEY",
  91. "defaultType": "spot"
  92. },
  93. {
  94. "name": "bybit_futures",
  95. "exchangeId": "bybit",
  96. "apiKey": "YOUR_API_KEY",
  97. "secret": "YOUR_SECRET_KEY",
  98. "defaultType": "swap"
  99. }
  100. ]
  101. }
  102. ```
  103. > **Important**: The configuration file must contain an `accounts` array at the root level, as shown above.
  104. > **Important**: If you run the server in HTTP+SSE mode (`--sse`), set `mcpBearerToken` in the same config file. Clients must send `Authorization: Bearer <mcpBearerToken>` on requests.
  105. 2. **Specify the Configuration File Path in Claude Desktop Settings**:
  106. ```json
  107. {
  108. "mcpServers": {
  109. "ccxt-mcp": {
  110. "command": "npx",
  111. "args": [
  112. "-y",
  113. "@lazydino/ccxt-mcp",
  114. "--config",
  115. "/path/to/ccxt-config.json"
  116. ]
  117. }
  118. }
  119. }
  120. ```
  121. > **Note**: When using a separate configuration file with the `--config` option, the server will look for the `accounts` array directly in the root of the JSON file, not in `mcpServers.ccxt-mcp.accounts` path.
  122. 3. **Running with External Configuration File from Command Line**:
  123. ```bash
  124. # Using custom configuration file
  125. npx @lazydino/ccxt-mcp --config /path/to/ccxt-config.json
  126. ```
  127. You can find an example configuration file at `config/ccxt-config.example.json` in the repository.
  128. > **Reasons to Use a Separate Configuration File**:
  129. >
  130. > - Prevents recursive reference issues
  131. > - Separates sensitive information like API keys
  132. > - Easier multi-environment configuration (development, testing, production)
  133. > - Improved configuration file version control
  134. ## Key Features
  135. - **Market Information Retrieval**:
  136. - List exchanges
  137. - View market information by exchange
  138. - Get price information for specific symbols
  139. - View order book information for specific symbols
  140. - Search historical OHLCV data
  141. - **Trading Functions**:
  142. - Create market/limit orders
  143. - Cancel orders and check status
  144. - View account balances
  145. - Check trading history
  146. - **Trading Analysis**:
  147. - Daily/weekly/monthly performance analysis
  148. - Win rate calculation (last 7 days, 30 days, all time)
  149. - Average profit/loss ratio (R-multiple)
  150. - Maximum consecutive loss/profit series analysis
  151. - Asset variation tracking
  152. - Comprehensive performance metrics
  153. - Trade pattern recognition
  154. - Period-based return calculations
  155. - **Position Management**:
  156. - Capital ratio trading (e.g., enter with 5% of account capital)
  157. - Futures market leverage setting (1-100x)
  158. - Dynamic position sizing (volatility-based)
  159. - Split buy/sell strategy implementation
  160. - **Risk Management**:
  161. - Technical indicator-based stop loss setting (e.g., lowest point among 10 candles on 5-minute chart)
  162. - Volatility-based stop loss/take profit (ATR multiples)
  163. - Maximum allowable loss limit (daily/weekly)
  164. - Dynamic take profit setting (trailing profit)
  165. ## How It Works
  166. ```
  167. User <--> AI Model(Claude/GPT) <--> MCP Protocol <--> CCXT MCP Server <--> Cryptocurrency Exchange API
  168. ```
  169. 1. **User**: Requests like "Tell me the Bitcoin price" or "Buy Ethereum on my Binance account"
  170. 2. **AI Model**: Understands user requests and determines which MCP tools/resources to use
  171. 3. **MCP Protocol**: Standardized communication between AI and CCXT MCP server
  172. 4. **CCXT MCP Server**: Communicates with cryptocurrency exchange APIs using the CCXT library
  173. 5. **Exchange API**: Provides actual data and executes trade orders
  174. ## Using with AI Models
  175. When registered with Claude Desktop, you can make the following types of requests to AI models:
  176. ### Cautions and Recommended Prompts
  177. When using AI models, consider the following cautions and use the prompt below for effective trading:
  178. ```
  179. Your goal is to execute trades using the ccxt tools as much as possible
  180. Cautions:
  181. - Accurately identify whether it's a futures market or spot market before proceeding with trades
  182. - If there's no instruction about percentage of capital or amount to use, always calculate and execute trades using the entire available capital
  183. ```
  184. **Notes:**
  185. - AI models sometimes confuse futures trading with spot trading.
  186. - Without clear guidance on trading capital size, AI might get confused.
  187. - Using the above prompt helps clearly communicate your trading intentions.
  188. ### Basic Query Examples
  189. ```
  190. Check and compare the current Bitcoin price on binance and coinbase.
  191. ```
  192. ### Advanced Trading Query Examples
  193. **Position Management**
  194. ```
  195. Open a long position on BTC/USDT futures market in my Bybit account (bybit_futures) with 5% of capital using 10x leverage.
  196. Enter based on moving average crossover strategy and set stop loss at the lowest point among the 12 most recent 5-minute candles.
  197. ```
  198. **Performance Analysis**
  199. ```
  200. Analyze my Binance account (bybit_main) trading records for the last 7 days and show me the win rate, average profit, and maximum consecutive losses.
  201. ```
  202. **Detailed Trading Analytics**
  203. ```
  204. Analyze my trading performance on the bybit_futures account for BTC/USDT over the last 30 days. Calculate win rate, profit factor, and identify any patterns in my winning trades.
  205. ```
  206. ```
  207. Show me the monthly returns for my bybit_main account over the past 90 days and identify my best and worst trading months.
  208. ```
  209. ```
  210. Analyze my consecutive wins and losses on my bybit_futures account and tell me if I have any psychological patterns affecting my trading after losses.
  211. ```
  212. ## Development
  213. ### Building from Source
  214. ```bash
  215. # Clone repository
  216. git clone https://github.com/lazy-dinosaur/ccxt-mcp.git
  217. # Navigate to project directory
  218. cd ccxt-mcp
  219. # Install dependencies
  220. npm install
  221. # Build
  222. npm run build
  223. ```
  224. ## Docker
  225. ### Build and Run with Docker Compose
  226. 1. Create a config file:
  227. ```bash
  228. cp config/ccxt-config.example.json config/ccxt-config.json
  229. ```
  230. Then fill in your real API keys in `config/ccxt-config.json`.
  231. Also set `mcpBearerToken` in that same config file.
  232. 2. Build image:
  233. ```bash
  234. docker compose build
  235. ```
  236. 3. Start the MCP server in background (SSE mode on localhost:2298):
  237. ```bash
  238. docker compose up -d
  239. ```
  240. 4. Verify local health endpoint:
  241. ```bash
  242. curl -H "Authorization: Bearer YOUR_MCP_TOKEN" http://127.0.0.1:2298/healthz
  243. ```
  244. This Compose setup runs MCP over HTTP+SSE (`/sse` + `/messages`) on localhost:2298 for reverse proxying.
  245. ### Remote MCP Client Configuration
  246. If your MCP client runs on another host, use an Nginx reverse proxy on this machine.
  247. 1. Copy `ccxt-mcp.nginx` to your Nginx config location and update certificate paths:
  248. ```bash
  249. sudo cp ccxt-mcp.nginx /etc/nginx/conf.d/ccxt-mcp.conf
  250. ```
  251. 2. Edit `/etc/nginx/conf.d/ccxt-mcp.conf` and set:
  252. - `ssl_certificate`
  253. - `ssl_certificate_key`
  254. - Authorization header forwarding (already included in this file)
  255. 3. Reload Nginx:
  256. ```bash
  257. sudo nginx -t && sudo systemctl reload nginx
  258. ```
  259. 4. In your MCP client, configure the MCP server URL to your TLS endpoint:
  260. - SSE URL: `https://YOUR_HOSTNAME_OR_IP:42299/sse`
  261. - Messages URL: `https://YOUR_HOSTNAME_OR_IP:42299/messages`
  262. - Header: `Authorization: Bearer YOUR_MCP_TOKEN`
  263. You can generate a strong token with:
  264. ```bash
  265. openssl rand -hex 32
  266. ```
  267. Config example:
  268. ```json
  269. {
  270. "mcpBearerToken": "YOUR_MCP_TOKEN",
  271. "accounts": [
  272. {
  273. "name": "bybit_main",
  274. "exchangeId": "bybit",
  275. "apiKey": "YOUR_API_KEY",
  276. "secret": "YOUR_SECRET_KEY"
  277. }
  278. ]
  279. }
  280. ```
  281. Port note:
  282. - `42298` is HTTP (redirect only)
  283. - `42299` is HTTPS
  284. - `2298` comes from `CCXT` on a phone keypad
  285. If your MCP client accepts command-based MCP servers instead of URL configuration, configure `ccxt-mcp` with:
  286. - Command: `docker`
  287. - Args:
  288. ```json
  289. [
  290. "run",
  291. "--rm",
  292. "-i",
  293. "-p",
  294. "127.0.0.1:2298:2298",
  295. "-v",
  296. "/absolute/path/to/ccxt-mcp/config/ccxt-config.json:/config/ccxt-config.json:ro",
  297. "ccxt-mcp:local",
  298. "--sse",
  299. "--host",
  300. "0.0.0.0",
  301. "--port",
  302. "2298",
  303. "--config",
  304. "/config/ccxt-config.json"
  305. ]
  306. ```
  307. Build the image first with `docker compose build`.
  308. ## 🤝 Contributing
  309. Contributions are welcome! Please feel free to submit a Pull Request.
  310. ## 📄 License
  311. Distributed under the MIT License. See the LICENSE file for more information.
  312. ## ❤️ Support
  313. If you find this project useful, please consider giving it a ⭐️ on GitHub!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.