Crypto MCP Server & Agent

这是一个使用 TypeScript 编写的加密货币 Model Context Protocol (MCP) 服务器，通过 Binance 公共 API 提供实时行情查询能力。

现在项目包含两个部分：

MCP 服务器：提供加密货币行情查询工具，可以接入 ChatGPT、Claude Desktop、Strands 或任何支持 MCP 的客户端
Agent：一个智能 Agent，通过 LLM API 自动调用 MCP 工具来回答用户问题，无需手动配置 MCP 客户端

🔧 功能概览

当前实现了 5 个强大的工具，覆盖从基础价格查询到深度市场分析：

① get_price — 获取实时价格

获取指定交易对的实时价格。

输入参数：

symbol：交易对符号，如 BTC、ETH、SOL（不区分大小写）
quote：报价货币，如 USDT、BUSD（默认 USDT）

输出：

实时价格
交易对符号
时间戳（Unix 和 ISO 格式）

使用示例：

"BTC 现在多少钱？"
→ 调用 get_price({ symbol: "BTC", quote: "USDT" })

② get_24h_stats — 获取24小时统计数据

获取交易对过去24小时的完整统计数据，包括涨跌幅、成交量、最高/最低价等。

输入参数：

symbol：交易对符号（如 BTC、ETH）
quote：报价货币（默认 USDT）

输出：

价格变化（绝对值和百分比）
当前价格、开盘价、最高价、最低价
24小时成交量、成交额
加权平均价
买卖盘价格

使用示例：

"ETH 今天涨了多少？"
→ 调用 get_24h_stats({ symbol: "ETH" })

③ get_ohlcv — 获取K线数据

获取技术分析所需的K线（蜡烛图）数据，支持多种时间间隔。

输入参数：

symbol：交易对符号
quote：报价货币（默认 USDT）
interval：K线时间间隔（1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M，默认 1h）
limit：返回的K线数量（1-1000，默认 500）

输出：

格式化的K线数组，每条包含：
- 开盘时间、收盘时间
- 开盘价、最高价、最低价、收盘价
- 成交量、成交额
- 成交笔数、主动买入量等

使用示例：

"给我 BTC 最近10小时的K线数据"
→ 调用 get_ohlcv({ symbol: "BTC", interval: "1h", limit: 10 })

④ get_symbol_overview — 智能综合概览 ⭐

智能组合工具，整合多个数据源，提供交易对的全面分析。

输入参数：

symbol：交易对符号
quote：报价货币（默认 USDT）

输出：

当前价格：实时价格
24小时涨跌：价格变化和百分比
最高/最低价：24小时价格区间
趋势判断：
- 趋势类型：上涨/下跌/盘整
- 趋势强度：-1 到 1 的数值
- 趋势描述：基于K线分析的详细说明
- 移动平均线分析
- RSI 指标
交易量分析：
- 交易量等级：高/中/低
- 交易量描述

使用示例：

"BTC 今天怎么样？属于上涨还是盘整？"
→ 调用 get_symbol_overview({ symbol: "BTC" })

这个工具特别适合回答综合性的市场分析问题，模型可以基于返回的数据生成自然语言回答。

⑤ get_order_book — 获取交易深度（订单簿）

查看市场流动性、深度和买卖盘强度，适合做交易分析。

输入参数：

symbol：交易对符号
quote：报价货币（默认 USDT）
limit：订单深度数量（5-5000，默认 100）

输出：

最佳买卖价：当前最优买价和卖价
价差分析：买卖价差（绝对值和百分比）
流动性分析：
- 买盘总量、卖盘总量
- 总流动性
- 买卖盘比例
- 买盘强度（强/弱/平衡）
前10档买卖盘明细：价格、数量、总额

使用示例：

"BTC 的买卖盘深度怎么样？"
→ 调用 get_order_book({ symbol: "BTC", limit: 20 })

🤖 Agent 使用指南

什么是 Agent？

Agent 是一个智能助手，可以自动理解你的问题，选择合适的工具获取数据，然后生成自然语言回答。无需手动配置 MCP 客户端，开箱即用！

快速开始

启动 MCP 服务器（HTTP 模式）：

npm run build
MCP_TRANSPORT=http PORT=8081 npm start

配置 Agent（创建并编辑 config.json）：

# 复制配置文件示例
cp config.json.example config.json

# 编辑 config.json，填入你的 API 配置
# 注意：config.json 已加入 .gitignore，不会被提交到版本控制

运行 Agent：

npm run agent "BTC 现在多少钱？"

Agent 功能特点

🎯 智能工具选择：自动根据问题选择合适的工具
🔄 多轮对话：支持多轮工具调用直到获得完整答案
📊 数据可视化：将原始数据转换为易读的自然语言
🛠️ 自动错误处理：工具调用失败时自动重试或使用替代方案
📝 详细日志：设置 DEBUG=1 查看详细的执行过程

📡 数据源说明

本项目使用 Binance 公开 REST API：

实时价格：GET /api/v3/ticker/price
24小时统计：GET /api/v3/ticker/24hr
K线数据：GET /api/v3/klines
订单簿：GET /api/v3/depth

无需 API Key，无限制地调用基础行情数据。

📦 环境要求

Node.js 18+
npm（或 yarn / pnpm）
允许访问 Binance API（网络连接）

🚀 安装与运行

1. 安装依赖

npm install

2. 编译项目

npm run build

3. 配置 Agent

Agent 通过 config.json 配置文件读取配置：

# 1. 复制配置文件示例
cp config.json.example config.json

# 2. 编辑 config.json，填入你的配置
# 编辑 config.json 文件，设置以下参数：
# - LLM_API_URL: LLM API 地址
# - LLM_API_KEY: LLM API 密钥
# - MCP_SERVER_URL: MCP 服务器地址
# - MODEL: LLM 模型名称

配置文件说明（config.json）：

LLM_API_URL: LLM API 地址（默认：https://llmapi.paratera.com）
LLM_API_KEY: LLM API 密钥（重要：不要提交到版本控制）
MCP_SERVER_URL: MCP 服务器地址（默认：http://localhost:8081/mcp）
MODEL: LLM 模型名称（默认：gpt-3.5-turbo，根据实际 API 支持的模型调整）

注意：

config.json 文件已加入 .gitignore，不会被提交到版本控制
如果 config.json 不存在，Agent 会使用默认配置并显示警告
参考 config.json.example 了解配置文件格式

4. 运行 MCP 服务器

# HTTP 模式（用于 Agent）
MCP_TRANSPORT=http PORT=8081 npm start

# 或 stdio 模式（用于 MCP 客户端）
npm start

5. 运行 Agent（推荐）

Agent 是最简单的使用方式，无需配置 MCP 客户端：

# 方式 1: 使用 npm 脚本
npm run agent "BTC 现在多少钱？"

# 方式 2: 直接运行
node agent.js "ETH 今天涨了多少？"

# 方式 3: 运行测试脚本
npm run test-agent

Agent 示例问题：

node agent.js "BTC 现在多少钱？"
node agent.js "ETH 今天涨了多少？"
node agent.js "BTC 今天怎么样？属于上涨还是盘整？"
node agent.js "BTC 的买卖盘深度怎么样？"
node agent.js "给我 BTC 最近10小时的K线数据"

6. 开发模式（热重载）

npm run dev

🧠 工作原理

MCP 服务器模式（传统方式）

MCP 客户端启动该服务器（通过 stdio 通信）
用户问模型："现在 BTC 价格多少？"
模型判断 → 调用 MCP 工具：get_price
MCP 服务器访问 Binance API → 返回价格
模型用结果生成自然语言回答

Agent 模式（推荐）

启动 MCP 服务器（HTTP 模式，监听 8081 端口）
用户运行 Agent：node agent.js "BTC 现在多少钱？"
Agent 获取 MCP 工具列表 → 转换为 LLM 工具格式
Agent 调用 LLM API → LLM 决定调用哪些工具
Agent 执行工具调用 → 从 MCP 服务器获取数据
Agent 将结果返回给 LLM → LLM 生成自然语言回答

Agent 的优势：

✅ 无需配置 MCP 客户端
✅ 开箱即用，直接通过命令行使用
✅ 自动工具发现和调用
✅ 支持多轮对话和工具调用循环

⚙️ MCP 客户端配置示例

Claude Desktop 配置

编辑 claude_desktop_config.json（macOS 路径：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
  "crypto-mcp": {
    "command": "node",
      "args": ["/path/to/trade_mcp/dist/server.js"],
    "transport": "stdio"
  }
}
}

其他 MCP 客户端

根据客户端文档配置，确保：

command: node
args: ["dist/server.js"]（使用绝对路径）
transport: stdio

配置好后即可在客户端中直接使用所有工具。

🔍 调试方式

方法 1: MCP Inspector（需要浏览器界面）

如果环境支持浏览器，推荐使用 MCP Inspector：

npx @modelcontextprotocol/inspector node dist/server.js

你可以：

查看当前服务器暴露的所有工具
单独测试每个工具调用
查看请求 / 响应细节

方法 2: 命令行测试脚本（服务器环境推荐）

如果服务器环境无法打开浏览器，可以使用命令行测试脚本：

# 1. 先编译项目
npm run build

# 2. 运行测试脚本（测试 MCP 服务器）
npm test
# 或
node test/test-server.js

测试脚本会：

启动 MCP 服务器
测试列出工具功能
测试所有5个工具的功能
显示详细的请求和响应信息

方法 3: 直接测试 Binance API

验证网络连接和 API 可用性：

node test/test-api-direct.js

这会直接调用 Binance API，不经过 MCP 服务器，用于诊断网络问题。

🎯 使用场景示例

场景 1: 简单价格查询

用户："BTC 现在多少钱？"
模型：调用 get_price → "BTC 当前价格为 $92,026.49 USDT"

场景 2: 市场分析

用户："BTC 今天怎么样？属于上涨还是盘整？"
模型：调用 get_symbol_overview → 
"BTC 今天表现良好，属于上涨趋势。当前价格 $92,028.73，
24小时涨幅 0.975%，最高价 $93,160，最低价 $88,608。
根据K线分析，呈现明显上涨趋势，交易量很高，市场活跃。"

场景 3: 技术分析

用户："给我 ETH 最近10小时的K线数据"
模型：调用 get_ohlcv({ symbol: "ETH", interval: "1h", limit: 10 })
→ 返回详细的K线数据供分析

场景 4: 流动性分析

用户："BTC 的买卖盘深度怎么样？"
模型：调用 get_order_book → 
"BTC 当前最佳买价 $92,026.49，最佳卖价 $92,026.50，
价差仅 0.0001%，流动性很好。买盘总量 $XXX，卖盘总量 $XXX，
买卖盘比例平衡，市场深度充足。"

➕ 如何扩展更多工具

你可以轻松添加更多 Binance API 工具，例如：

历史数据查询：获取更长时间范围的数据
技术指标计算：MACD、布林带、KDJ 等
多交易所支持：整合 OKX、Coinbase 等
价格提醒：监控价格变化
交易功能（需要 API Key）：下单、查询订单等

参考现有工具的实现方式，在 src/server.ts 中添加新的 Schema 和函数即可。

⚠️ 注意事项

API 速率限制：Binance 公共 API 有速率限制（当前非常宽松），如需高频请求建议添加缓存机制。
数据格式：MCP 工具返回时应保持 JSON 格式，AI 才能稳定理解。
交易功能：若要扩展版本到交易/下单功能，需要使用 Binance API Key（本项目默认未涉及资金操作）。
网络连接：确保服务器可以访问 api.binance.com。
错误处理：所有工具都包含完善的错误处理，会返回友好的错误信息。
配置文件安全：
- config.json 文件已加入 .gitignore，不会被提交到版本控制
- 不要将包含真实 API Key 的 config.json 文件提交到版本控制
- 使用 config.json.example 作为模板，复制为 config.json 后填入你的配置
Agent 使用：
- 使用 Agent 前需要先启动 MCP 服务器（HTTP 模式）
- 确保 LLM API 支持工具调用（function calling）功能
- 如果遇到工具调用失败，可以设置 DEBUG=1 查看详细日志

📊 技术栈

TypeScript：类型安全的开发体验
Zod：强大的参数验证
MCP SDK：Model Context Protocol 官方 SDK
Binance API：可靠的加密货币数据源

📝 更新日志

v1.1.0

✅ 新增 Agent 功能，无需配置 MCP 客户端即可使用
✅ 配置文件化，支持环境变量和配置文件两种方式
✅ 改进参数解析，修复 LLM 返回字符串参数的问题
✅ 增强错误处理和调试信息

v1.0.0

✅ 实现 5 个核心工具
✅ 智能趋势分析（移动平均线、RSI）
✅ 完整的测试覆盖
✅ 中文友好的文档和描述

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

crypto-mcp-server

Crypto MCP Server & Agent

🔧 功能概览

① get_price — 获取实时价格

② get_24h_stats — 获取24小时统计数据

③ get_ohlcv — 获取K线数据

④ get_symbol_overview — 智能综合概览 ⭐

⑤ get_order_book — 获取交易深度（订单簿）

🤖 Agent 使用指南

什么是 Agent？

快速开始

Agent 功能特点

更多信息

📡 数据源说明

📦 环境要求

🚀 安装与运行

1. 安装依赖

2. 编译项目

3. 配置 Agent

4. 运行 MCP 服务器

5. 运行 Agent（推荐）

6. 开发模式（热重载）

🧠 工作原理

MCP 服务器模式（传统方式）

Agent 模式（推荐）

⚙️ MCP 客户端配置示例

Claude Desktop 配置

其他 MCP 客户端

🔍 调试方式

方法 1: MCP Inspector（需要浏览器界面）

方法 2: 命令行测试脚本（服务器环境推荐）

方法 3: 直接测试 Binance API

🎯 使用场景示例

场景 1: 简单价格查询

场景 2: 市场分析

场景 3: 技术分析

场景 4: 流动性分析

➕ 如何扩展更多工具

⚠️ 注意事项

📊 技术栈

📝 更新日志

v1.1.0

v1.0.0

🤝 贡献

📄 许可证

Reviews