Metadata-Version: 2.4
Name: mcp-ccxt
Version: 1.0.0
Summary: Open-source MCP Server for Crypto Exchanges via CCXT
Project-URL: Homepage, https://github.com/dante1989/mcp-ccxt
Project-URL: Repository, https://github.com/dante1989/mcp-ccxt
Project-URL: Issues, https://github.com/dante1989/mcp-ccxt/issues
Project-URL: Changelog, https://github.com/dante1989/mcp-ccxt/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/dante1989/mcp-ccxt#readme
Author: dante1989
License: MIT
License-File: LICENSE
Keywords: ai-agent,ccxt,crypto,exchange,mcp,trading
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: cachetools>=5.3
Requires-Dist: ccxt>=4.4
Requires-Dist: fastmcp>=2.3
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: pydantic>=2.5
Requires-Dist: structlog>=24.1
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-ccxt

Open-source MCP Server for Crypto Exchanges via CCXT.

Connect AI agents (Claude, Cursor, CrewAI, LangChain) to 100+ crypto exchanges through the Model Context Protocol.

## Features

- **13 tools**: market data, trading, account management
- **100+ exchanges**: Binance, OKX, Bybit, Coinbase, Kraken, and more via [CCXT](https://github.com/ccxt/ccxt)
- **2 transports**: stdio (local) and Streamable HTTP (remote/Docker)
- **Async only**: built on `ccxt.async_support` for performance
- **Safe by default**: sandbox mode on, rate limiting built-in, no credential leaks

## Quickstart (< 5 minutes)

### 1. Install

```bash
pip install mcp-ccxt
```

### 2. Configure

Create `config.json`:

```json
{
  "accounts": [
    {
      "name": "binance-test",
      "exchange_id": "binance",
      "api_key": "YOUR_API_KEY",
      "secret": "YOUR_SECRET",
      "sandbox": true,
      "default_type": "spot"
    }
  ]
}
```

### 3. Test connectivity

```bash
mcp-ccxt test-sandbox --config config.json
# [OK] binance-test: connected (BTC/USDT = 50000.0)
```

### 4. Run server

**stdio** (Claude Desktop / Cursor):

```bash
mcp-ccxt run --config config.json
```

**Streamable HTTP** (remote / Docker):

```bash
mcp-ccxt run --config config.json --transport streamable-http --host 0.0.0.0 --port 8000
```

### Claude Desktop setup

Add to Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ccxt": {
      "command": "mcp-ccxt",
      "args": ["run", "--config", "/path/to/config.json"]
    }
  }
}
```

See also `examples/claude_desktop_config.json`.

### Cursor setup

Add to Cursor MCP settings:

```json
{
  "mcpServers": {
    "ccxt": {
      "command": "mcp-ccxt",
      "args": ["run", "--config", "/path/to/config.json"]
    }
  }
}
```

See also `examples/cursor_config.json`.

### Docker (remote deployment)

```bash
docker compose -f docker-compose.example.yml up -d
```

The server listens on `http://localhost:8000` (Streamable HTTP). Connect from CrewAI or any MCP client, for example:

```text
http://localhost:8000/mcp
```

See `examples/crewai_example.py` for a CrewAI sample.

## Tools reference

### Market data (5 tools)

| Tool | Description |
|------|-------------|
| `fetch_ticker` | Current price, spread, volume for a symbol |
| `fetch_ohlcv` | OHLCV candles (1m to 1M timeframes) |
| `fetch_order_book` | Bids/asks with spread calculation |
| `fetch_markets` | All markets with limits + precision |
| `list_exchanges` | All supported exchange IDs |

### Trading (4 tools)

| Tool | Description |
|------|-------------|
| `create_order` | Place market or limit order |
| `cancel_order` | Cancel an open order |
| `edit_order` | Modify existing order (exchange-dependent) |
| `fetch_open_orders` | List open orders |

### Account (4 tools)

| Tool | Description |
|------|-------------|
| `fetch_balance` | Account balances (zero-balance filtered) |
| `fetch_my_trades` | Trade history for a symbol |
| `fetch_positions` | Open futures positions |
| `get_server_info` | Server version + connected exchanges |

## Configuration

### Exchange accounts (`config.json`)

```json
{
  "accounts": [
    {
      "name": "unique-account-name",
      "exchange_id": "binance",
      "api_key": "...",
      "secret": "...",
      "password": "...",
      "sandbox": true,
      "default_type": "spot"
    }
  ]
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Unique identifier for this account |
| `exchange_id` | yes | CCXT exchange ID (e.g. `binance`, `okx`) |
| `api_key` | no | API key (required for trading) |
| `secret` | no | API secret |
| `password` | no | Passphrase (OKX requires this) |
| `sandbox` | no | Enable testnet mode (default: `true`) |
| `default_type` | no | Market type: `spot`, `swap`, `future` (default: `spot`) |

### Transport options

| Flag | Default | Description |
|------|---------|-------------|
| `--transport` | `stdio` | `stdio` or `streamable-http` |
| `--host` | `127.0.0.1` | Bind address (use `0.0.0.0` for Docker) |
| `--port` | `8000` | HTTP port |
| `--log-level` | `INFO` | Logging level |

## Security

- **Sandbox on by default** — testnet mode reduces accidental real trades
- **No credential leaks** — API keys never appear in tool responses or error messages
- **SecretStr credentials** — keys masked in logs and repr()
- **Rate limiting** — CCXT built-in rate limiter (no custom implementation)

## Requirements

- Python 3.11+
- CCXT 4.4+
- FastMCP 2.3+

## License

MIT
