🚀 Binance MCP Server

基于ccxt库为Binance交易所开发的MCP（Model Context Protocol）服务，让AI agents（如Claude Code）能够安全、高效地进行数字货币交易操作。提供完整的现货、期货、期权交易功能支持。

✨ 功能特性

🎯 专为非技术用户设计

• 零编程经验要求 - 通过简单的CLI命令即可完成所有配置
• AI助手友好 - 完美兼容Claude Code等AI编程助手
• 一键安装部署 - 单条命令完成安装和配置

🔧 技术特性

• 内置配置优化 - 自动优化交易参数和连接配置
• 高效执行 - 基于ccxt库的稳定交易执行
• 零额外成本 - 不增加任何交易费用

🛡️ 企业级安全

• 本地加密存储 - API密钥使用Fernet对称加密
• 多账户隔离 - 支持现货、期货、沙盒环境分离管理
• 无网络传输 - 密钥仅在本地存储，绝不上传
• 权限最小化 - 仅申请必要的API权限

📊 完整交易支持

• 现货交易 - 市价单、限价单、止损单等
• 期货合约 - USD-M、币本位期货，支持杠杆调整
• 期权交易 - Call/Put期权买卖
• 账户管理 - 余额查询、持仓管理、交易历史

🔧 完整的MCP工具集（30个工具）

🏪 现货交易

• create_spot_order - 创建现货订单

📋 订单管理

• cancel_order - 取消订单
• get_open_orders - 查看待成交订单
• get_order_status - 查询单个订单状态
• get_my_trades - 获取成交记录
• cancel_all_orders - 批量取消订单

🛡️ 风险控制

• create_stop_loss_order - 创建止损订单
• create_take_profit_order - 创建止盈订单
• create_stop_limit_order - 创建止损限价订单
• create_trailing_stop_order - 创建追踪止损订单
• create_oco_order - 创建OCO订单

📊 市场数据

• get_ticker - 获取价格行情
• get_order_book - 获取订单簿深度
• get_klines - 获取K线数据
• get_funding_rate - 获取资金费率

🎯 期权交易

• create_option_order - 创建期权订单
• get_option_chain - 获取期权链
• get_option_positions - 获取期权持仓
• get_option_info - 获取期权合约信息

📈 合约交易

• create_contract_order - 创建合约订单
• close_position - 一键平仓
• get_futures_positions - 获取期货持仓详情

💰 账户管理

• get_balance - 查询余额
• get_positions - 查看持仓
• set_leverage - 设置杠杆倍数
• set_margin_mode - 设置保证金模式
• transfer_funds - 账户间转账

ℹ️ 系统工具

• get_server_info - 服务器状态信息

🚀 快速开始

1. 安装

pip install git+https://github.com/shanrichard/binance-mcp.git

2. 配置账户

# 交互式配置API密钥
binance-mcp config

# 查看已配置的账户
binance-mcp list

3. 启动服务

# 前台运行（显示日志）
binance-mcp start

# 后台运行（推荐）
binance-mcp start -d

# 自定义端口
binance-mcp start --port 9002

4. 在Claude Code中使用

启动服务后，在Claude Code中直接说：

"帮我查看BTC的当前价格"

"用我的现货账户买入0.001个BTC"

"查看我的账户余额"

Claude Code会自动调用相应的MCP工具完成操作！

🤖 AI框架集成

LangGraph Agent集成

将Binance MCP工具集成到您现有的LangGraph Agent中：

from mcp_langchain import MCPToolkit  # 或 langchain_community.adapters.mcp

# 连接到MCP服务器，获取工具
mcp_toolkit = MCPToolkit(
    server_command="python",
    server_args=["-m", "binance_mcp.simple_server"],
    server_env={}
)

# 获取转换后的LangChain工具
binance_tools = mcp_toolkit.get_tools()

# 添加到您现有的工具列表
your_existing_tools.extend(binance_tools)

# 绑定到LLM
llm_with_tools = llm.bind_tools(your_existing_tools)

其他AI框架

本项目遵循标准MCP协议，可与任何支持MCP的AI框架集成：

• Anthropic Claude - 原生支持
• OpenAI Assistants - 通过MCP适配器
• LangChain/LangGraph - 通过mcp-langchain
• CrewAI - 通过MCP工具适配
• AutoGen - 通过MCP协议集成

快速测试集成

# 测试工具是否正常加载
tools = mcp_toolkit.get_tools()
print(f"加载了 {len(tools)} 个交易工具")

# 测试服务器连接
server_info_tool = next(t for t in tools if t.name == "get_server_info")
result = server_info_tool.invoke({})
print(f"服务器状态: {result}")

# 测试价格查询
ticker_tool = next(t for t in tools if t.name == "get_ticker")
btc_price = ticker_tool.invoke({"symbol": "BTC/USDT"})
print(f"BTC价格: {btc_price}")

🎉 功能完整度

通过集成Binance MCP，您的AI Agent可以：

📊 完整交易生态

• 现货交易 - 买卖各种数字货币
• 期货合约 - 杠杆交易、一键平仓
• 期权策略 - Call/Put期权买卖
• 风险管控 - 止损止盈、追踪止损、OCO订单

📈 深度市场分析

• 实时价格 - 获取各种交易对价格
• K线数据 - 多种时间周期历史数据
• 订单簿深度 - 买卖盘深度分析
• 资金费率 - 期货合约资金费率

💰 专业账户管理

• 多账户支持 - 现货、期货、期权账户
• 杠杆设置 - 动态调整杠杆倍数
• 保证金模式 - 全仓/逐仓切换
• 资金划转 - 账户间资金管理

🛡️ 企业级安全

• 本地加密 - API密钥本地加密存储
• 权限最小化 - 仅授予必要权限
• 合规返佣机制 - 支持合作伙伴返佣计划
• 多环境支持 - 生产/沙盒环境隔离

🚀 30个专业交易工具，构建完整的数字货币交易AI生态系统！

📋 详细使用指南

配置API密钥

1. 获取API密钥：

   • 登录Binance
   • 前往 API管理 页面
   • 创建新的API密钥
   • 权限设置：勾选"现货与杠杆交易"和"期货交易"
   • 重要：启用IP白名单限制

2. 配置密钥：

   binance-mcp config
   

   按提示输入：

   • 账户ID（自定义名称）
   • API Key
   • Secret Key
   • 是否为沙盒环境
   • 账户描述

服务管理命令

# 查看帮助
binance-mcp --help

# 查看服务状态
binance-mcp status

# 停止服务
binance-mcp stop

# 测试连接
binance-mcp test <account_id>

# 备份配置
binance-mcp backup

高级配置

多账户管理：

# 添加现货账户
binance-mcp config --account-id spot_main

# 添加期货账户  
binance-mcp config --account-id futures_main

# 添加沙盒测试账户
binance-mcp config --account-id sandbox_test --sandbox

自定义服务器设置：

# 监听所有网卡
binance-mcp start --host 0.0.0.0

# 使用自定义端口
binance-mcp start --port 8888

🔧 故障排除

常见问题

**Q: 出现"Functions with kwargs are not supported as tools"错误？

A: 这是旧版本的问题，请更新：

pip uninstall binance-mcp -y && pip install git+https://github.com/shanrichard/binance-mcp.git

Q: API密钥认证失败？

A: 检查以下几点：

1. API密钥是否正确复制（注意空格）
2. 是否启用了必要的权限（现货/期货交易）
3. 是否设置了IP白名单限制
4. 沙盒/生产环境是否匹配

Q: 服务无法启动？

A: 检查端口是否被占用：

# 查看端口占用
lsof -i :9001

# 使用其他端口
binance-mcp start --port 9002

Q: Claude Code找不到MCP工具？

A: 确保：

1. 服务正在运行：binance-mcp status
2. 重启Claude Code
3. 检查MCP配置文件

日志查看

# 前台运行查看实时日志
binance-mcp start

# 后台运行的日志位置
~/.config/binance-mcp/logs/

诊断和调试工具

项目提供了专业的诊断工具帮助快速定位问题：

# 权限诊断工具 - 全面检查API权限配置
python diagnose_permissions.py

# 统一账户调试工具 - 检测统一账户模式配置
python debug_unified_account.py

# 集成测试 - 验证所有功能是否正常
python integration_test.py

权限诊断功能：

• ✅ 现货、期货、期权权限检查
• ✅ 网络连接和IP白名单检查
• ✅ 详细错误码解释和修复建议
• ✅ 权限配置分步指导

统一账户调试功能：

• ✅ 自动检测账户类型（普通/统一）
• ✅ 提供配置修改建议
• ✅ SHIB交易符号说明
• ✅ 实时余额和价格查询

🔄 更新指南

检查更新

# 查看当前版本
binance-mcp --version

# 查看最新版本
curl -s https://api.github.com/repos/shanrichard/binance-mcp/releases/latest | grep '"tag_name"'

更新到最新版本

方法1：重新安装（推荐）

pip uninstall binance-mcp -y && pip install git+https://github.com/shanrichard/binance-mcp.git

方法2：强制重装

pip install --force-reinstall git+https://github.com/shanrichard/binance-mcp.git

方法3：指定版本

pip install git+https://github.com/shanrichard/binance-mcp.git@v1.0.1

更新说明

• ✅ 配置保持不变 - 更新不会影响已配置的账户
• ✅ 向后兼容 - 新版本兼容旧配置
• ✅ 热更新支持 - 无需重新配置API密钥

🏗️ 开发者指南

本地开发

# 克隆代码
git clone https://github.com/shanrichard/binance-mcp.git
cd binance-mcp

# 安装开发依赖
pip install -e .[dev]

# 运行测试
pytest

# 运行集成测试
python integration_test.py

测试覆盖

# 单元测试
pytest tests/unit/ -v

# 测试覆盖率
pytest --cov=binance_mcp --cov-report=html

代码结构

binance-mcp/
├── binance_mcp/              # 📦 核心代码包
│   ├── __init__.py           # 包初始化
│   ├── broker.py             # Broker ID注入工厂
│   ├── cli.py                # CLI命令行接口
│   ├── config.py             # 配置管理（加密存储）
│   ├── server.py             # 完整MCP服务器
│   ├── simple_server.py      # 简化MCP服务器
│   └── tools.py              # MCP工具实现
│
├── tests/                    # 🧪 测试套件
│   ├── conftest.py           # 测试配置
│   └── unit/                 # 单元测试
│       ├── test_broker_simple.py
│       ├── test_config.py
│       └── test_tools_simple.py
│
├── examples/                 # 📚 示例代码
│   ├── LANGGRAPH_MCP_GUIDE.md   # LangGraph集成指导
│   └── test_unified_trading.py  # 统一账户测试示例
│
├── integration_test.py       # ✅ 集成测试
├── diagnose_permissions.py   # 🔧 权限诊断工具
├── debug_unified_account.py  # 🐛 统一账户调试工具
│
└── [配置文件]                # ⚙️ 项目配置
    ├── README.md
    ├── LICENSE
    ├── pyproject.toml
    ├── setup.py
    ├── requirements.txt
    └── requirements-dev.txt

🤝 贡献指南

提交Issue

遇到问题请提交Issue，包含：

• 操作系统版本
• Python版本
• 完整错误信息
• 复现步骤

贡献代码

1. Fork项目
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add some amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交Pull Request

⚠️ 风险提醒

交易风险

• 数字货币交易具有高风险，可能导致资金损失
• 建议先在沙盒环境充分测试
• 设置合理的止损和仓位管理
• 不要投入超过承受能力的资金

技术风险

• 确保API密钥安全，不要分享给他人
• 定期备份配置文件
• 在受信任的网络环境中使用
• 保持软件更新到最新版本

合规提醒

• 遵守当地法律法规
• 了解税务申报义务
• 符合反洗钱要求

📞 支持与反馈

• GitHub Issues: 提交问题
• 讨论区: GitHub Discussions
• 文档: 项目Wiki

📄 许可证

本项目采用 MIT License 开源协议。

🙏 致谢

• ccxt团队 - 提供优秀的交易所API统一库
• FastMCP团队 - 提供高性能的MCP服务器框架
• 开源社区 - 感谢每一位贡献代码和反馈的开发者

---

<div align="center">

⭐ 如果这个项目对您有帮助，请给我们一个Star！⭐

🏠 首页 • 📖 文档 • 🐛 问题反馈 • 💡 功能建议

</div>