AI导哈

加密货币交易MCP服务器

一个基于Python、FastMCP和CCXT构建的生产级加密货币交易MCP服务器，为AI代理提供安全的、类型安全的交易所操作访问，包括余额查询、订单管理和市场数据获取。

  • by reynaldoqs
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 reynaldoqs/mcp_trader

使用说明

交易MCP服务器

一个用于加密货币交易的、已准备好投入生产的模型上下文协议（MCP）服务器，采用Python、FastMCP和CCXT构建。该服务器为AI代理提供安全、类型安全的交易所操作访问权限，包括余额查询、订单管理和市场数据检索。

🚀 功能特性

  • 类型安全架构使用 Pydantic 进行完整的类型提示验证
  • Exchange 集成基于CCXT的客户端，支持多个交易所
  • MCP协议使用工具、资源和提示实现FastMCP
  • 模块化设计服务、核心类型和配置之间的职责清晰分离
  • 基于环境的配置使用 python-dotenv 实现安全的凭据管理
  • 全面日志记录使用 loguru 进行结构化日志记录
  • 错误处理用于稳健错误管理的自定义异常层次结构

📁 项目结构

trading-mcp-py/
├── main.py                    # Application entry point
├── requirements.txt           # Python dependencies
├── pyproject.toml            # Project metadata
├── .env.example              # Environment variables template
├── AGENTS.md                 # Agent architecture documentation
└── src/
    ├── __init__.py           # Package exports
    ├── config/               # Configuration management
    │   ├── settings.py       # Pydantic settings with env loading
    │   └── logging.py        # Logging configuration
    ├── core/                 # Core types and exceptions
    │   ├── types.py          # Trading types (Order, Position, etc.)
    │   └── exceptions.py     # Custom exception classes
    ├── services/             # Business logic layer
    │   ├── exchange_client.py    # CCXT exchange wrapper
    │   └── balance_service.py    # Balance operations
    ├── mcp/                  # MCP protocol implementation
    │   ├── server.py         # MCP server setup
    │   ├── tools.py          # MCP tools (trading operations)
    │   ├── resources.py      # MCP resources (data access)
    │   └── resources_helper.py   # Helper functions
    └── server/               # Legacy server code
        └── mcp_server.py

关键组件

  • **config/**基于环境的配置，使用Pydantic进行验证
  • **core/**类型定义（订单方向、订单类型、持仓等）和异常处理
  • **services/**交换客户端封装和业务逻辑服务
  • **mcp/**MCP协议实现（工具、资源、提示）

🛠️ 设置

先决条件

  • Python 3.11+
  • 紫外线 （推荐使用）或 pip

安装

  1. 克隆仓库

    cd trading-mcp-py

  2. 创建并激活虚拟环境

    # Using uv (recommended)
uv venv .venv
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

  3. 安装依赖项

    uv pip install -r requirements.txt

  4. 配置环境变量

    cp .env.example .env

    编辑 .env 附上您的兑换凭证：

    EXCHANGE_API_KEY=your_api_key_here
EXCHANGE_API_SECRET=your_api_secret_here

🚀 运行服务器

开发模式（推荐）

以开发模式运行MCP服务器，并启用热重载：

mcp dev main.py

生产模式

直接运行服务器：

python main.py

或者使用紫外线：

uv run python main.py

验证与检查

检查MCP服务器配置并验证设置：

npx @modelcontextprotocol/inspector uv run main.py

Claude 桌面集成

要在Claude Desktop中使用此MCP服务器，请在您的Claude Desktop配置文件中添加以下配置：

地点：

在以下路径创建或编辑Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "Trading MCP": {
      "command": "/Users/Username/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/Username/Projects/MPCs/trading-mcp-py",
        "run",
        "main.py"
      ]
    }
  }
}

注： 更新配置中的路径以匹配您的本地设置：

  • 替换 /Users/rey/.local/bin/uv 使用您的UV安装路径（通过以下方式找到： which uv)
  • 替换 /Users/rey/Projects/MPCs/trading-mcp-py 与您的项目目录路径一起

添加配置后，请重启Claude Desktop以使更改生效。

🔧 配置

该项目使用 Pydantic 进行类型安全的配置管理。所有设置都可以通过环境变量进行配置：

交换设置

  • EXCHANGE_API_KEY你的交易所API密钥
  • EXCHANGE_API_SECRET您的交易所API密钥
  • EXCHANGE_SANDBOX_MODE启用沙盒/测试网模式（默认：true）
  • EXCHANGE_RATE_LIMIT启用速率限制（默认：true）
  • EXCHANGE_DEFAULT_TYPE订单类型 - '现货'、'期货' 或 '保证金'（默认：期货）

MCP 设置

  • MCP_SERVER_NAME服务器名称（默认：交易MCP）

日志设置

  • LOG_LEVEL日志级别（默认：INFO）
  • LOG_FORMAT日志格式字符串
  • LOG_FILE_PATH日志文件路径
  • DEBUG启用调试模式（默认：false）
  • LOG_ROTATION日志轮转策略（默认：1天）
  • LOG_RETENTION日志保留策略（默认：30天）

通用设置

  • ENVIRONMENT运行时环境 - 'development'（开发）或 'production'（生产）（默认：production）

📚 MCP 工具与资源

可用工具

  • **open_market_long(symbol, usdt_amount)**以市场价格开仓做多
  • **open_market_short(symbol, usdt_amount)**以市场价格开仓做空
  • **open_limit_long(symbol, usdt_amount, price)**设置限价买单以开仓做多
  • **open_limit_short(symbol, usdt_amount, price)**设置限价卖出以开仓做空
  • **close_position(symbol)**平仓某交易品种的所有头寸
  • **get_balance()**返回格式化后的账户余额

可用资源

  • **account://balance**实时账户余额数据

⚡ 快速入门：常见操作

  1. 查看你的余额

    • 资源： account://balance
    • 工具： get_balance()

  2. 开仓（或建立仓位）

    • 在市场上存在已久： open_market_long(symbol="BTC/USDT" or "BTCUSDT", usdt_amount=50)
    • 在市场上做空： open_market_short(symbol="BTC/USDT" or "BTCUSDT", usdt_amount=50)
    • 长期无上限： open_limit_long(symbol, usdt_amount, price)
    • 限价卖出（或：有限制的卖出） open_limit_short(symbol, usdt_amount, price)

  3. 平仓

    • close_position(symbol)

注释：

  • 符号应与您的交易所格式相匹配（例如。， BTCUSDT 在Binance上）。如果不确定，请使用通过CCXT从您的交易所返回的确切符号。
  • 确保您的API密钥有足够的余额和正确的权限。

🏗️ 建筑学

这个项目采用了模块化、分层的架构：

  1. 配置层 (config/): 使用 Pydantic 进行基于环境的设置
  2. 核心层 (core/): 类型定义和异常
  3. 服务层 (services/): 业务逻辑与交换集成
  4. 协议层 （mcp/): MCP服务器实现
  5. 应用层 (main.py): 入口点和初始化

有关详细的代理架构模式，请参阅 `AGENTS.md` 翻译成中文是：`代理.md`（或根据上下文，也可以翻译为“代理列表.md”、“代理配置.md”等，具体取决于文件内容）。

🧪 测试

使用 pytest 运行测试：

pytest

测试环境加载中：

python test_env_loading.py

📖 文档

🔐 安全最佳实践

  • 永远不要承诺 .env 文件或API凭据
  • 在开发时使用沙盒/测试网模式
  • 定期轮换API密钥
  • 实施适当的速率限制
  • 使用 Pydantic 验证所有输入
  • 在可能的情况下使用只读API密钥

🤝 贡献（或“参与贡献”）

  1. 遵循既定的模式 AGENTS.md
  2. 为所有函数使用类型提示
  3. 为新功能添加测试
  4. 更新文档
  5. 遵循Python最佳实践（PEP 8）

📝 许可证

[在此添加您的许可证]

🐛 故障排除

导入错误

确保你是在项目根目录下运行，并且已激活虚拟环境。

Exchange 连接问题

  • 验证API凭证 .env
  • 检查测试网是否启用了沙盒模式
  • 确保您的网络可以访问交易所API

MCP服务器无法启动

  • 检查日志以获取详细的错误信息
  • 使用检查器工具验证配置
  • 确保所有依赖项都已安装

📞 支持

对于问题和疑问：

相关 MCP