用途
crypto-market-data-mcp 是一个只读的 Model Context Protocol（MCP）服务器，用于向任意 AI 智能体（如 Claude、Cursor、Cline、Windsurf 等）提供实时加密货币市场数据。它通过 CCXT 接入 100 多个交易所，无需 API 密钥，全部使用公开端点。
主要能力
- 提供价格、资金费率、未平仓合约、多空比、订单簿和 K 线等市场数据。
- 支持的交易所包括 bybit、binance、okx、hyperliquid、gate、kucoin，并可在 SUPPORTED_EXCHANGES 中添加更多 CCXT 交易所 ID。
- compare_funding 工具是核心差异点：在一次并发调用中比较各交易所的资金费率，找出支付最高与最低的场所，即资金费率套利机会。由于各交易所资金费率结算周期不同（Hyperliquid 每小时，其他多为 8 小时），原始费率不可直接比较，因此比较前会先年化（apr_pct）。
- 配套服务器 Crypto Derivatives Intelligence 可在此基础上提供更深入的分析，如扣除费用后的资金费率套利机会（盈亏平衡天数、可执行深度）、未平仓合约与价格背离、清算区域、持仓极端情况和市场状态分类，每个功能一次工具调用。
使用方式
- 可通过 MCPize 即时使用，无需本地安装，连接地址为 https://mcpize.com/mcp/crypto-market-data。
- 也可在本地以 stdio 模式运行，用于单用户开发。
- 与 Claude Desktop 配合使用时，将 claude_desktop_config.example.json 复制到 Claude Desktop 配置文件中（macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 路径为 %APPDATA%\Claude\claude_desktop_config.json），并调整路径。
- 交易对格式：永续合约如 BTC/USDT:USDT；常见简写会自动规范化，btc、BTCUSDT、BTC-USDT 均可使用（资金费率和未平仓合约工具会落到永续合约形式）。
生产级设计
- 对瞬时网络错误进行指数退避重试（最多 3 次）。
- 每请求和整体超时（10 秒 / 25 秒），避免某个交易所挂起导致调用停滞。
- 能力守卫：不会调用交易所不支持的方法，而是返回清晰错误并列出支持该方法的交易所（见 get_capabilities）。
- 结构化错误（{"error": {type, message, retryable, supported_exchanges}}）而非崩溃，智能体始终能获得可解析的响应。
- TTL 响应缓存（重复调用约快 660 倍，缓解速率限制）。
- 每个工具都有输入验证和限制值钳制。
- 保证交易所清理；仅向 stderr 记录日志（对 stdio 传输安全）。
认证与计费（HTTP 模式）
- 托管的 HTTP 传输受门控，这是其可计费的原因。本地 stdio 保持开放，供单用户开发。
- 客户端发送 Authorization: Bearer <api-key>。每个密钥映射到 client_id 和 tier；未知或缺失密钥返回 401。
- 层级（auth.py → TIERS）设置每分钟速率和每月配额：free 为 10 请求/分钟、1,000 次/月；pro 为 120 请求/分钟、100,000 次/月；ultra 为 600 请求/分钟、2,000,000 次/月。
- 超出限制时返回干净的 ToolError（Rate limit exceeded… / Monthly quota exceeded…），不会崩溃。
- 配置密钥（两种来源，文件优先）。若 HTTP 模式下未设置密钥，会生成一个一次性演示密钥（tier=pro）并打印到 stderr，以便立即测试。
网关部署
若部署在已对订阅者进行认证和限流的平台（如 MCPize）之后，可设置 CRYPTO_MCP_DISABLE_AUTH=1。服务器将信任网关并跳过自身认证与限流，避免双重认证和双重限流。仅当容器只能通过该网关访问时才应这样做。
适用场景
- AI 智能体需要实时加密货币行情数据时。
- 需要比较不同交易所资金费率、寻找套利机会的场景。
- 需要订单簿、K 线、未平仓合约等数据进行分析或策略开发。
限制
- 只读服务器，不提供交易执行功能。
- 本地 stdio 模式无认证，仅适合单用户开发。
- HTTP 模式有速率和配额限制，超出会返回错误。
- 支持的交易所默认限于 bybit、binance、okx、hyperliquid、gate、kucoin，需手动添加更多 CCXT 交易所 ID。
- 未来计划包括更激进地缓存热门符号以降低延迟，以及可选的 websocket 流式传输实时订单簿/交易，目前暂未提供。
