btc-price-mcp

v1.0.1

Published

10 months ago

A Model Context Protocol (MCP) server that provides real-time Bitcoin price data for Claude AI and Cursor

0High
0Medium
0Low

wanglinlinhaoyangde

bitcoin btc cryptocurrency mcp model-context-protocol claude cursor ai price api

Bitcoin Price MCP Server

一个基于 Model Context Protocol (MCP) 的服务器，为 Claude AI 和 Cursor 等工具提供实时比特币价格数据访问。该项目支持多种运行模式，既可以作为命令行工具使用，也可以作为 MCP 服务器集成到 AI 应用中。

📋 目录

✨ 功能特性

实时价格查询: 获取比特币当前价格、24小时涨跌幅和市值信息
双 API 支持: 同时支持 CoinMarketCap 和 CoinGecko API
自动回退机制: 当 CoinMarketCap API 不可用时，自动切换到 CoinGecko API
多种运行模式:
- CLI 模式：作为命令行工具直接使用
- MCP 服务器模式：通过 HTTP 服务器提供 MCP 协议支持
- SSE 支持：提供 Server-Sent Events 端点，供 Cursor 等工具连接
彩色终端输出: 美观的命令行界面，支持颜色高亮显示
健康检查端点: 提供 /health 端点用于服务状态监控

🛠 技术栈

TypeScript: 主要开发语言
Node.js: 运行时环境
axios: HTTP 客户端，用于 API 请求
dotenv: 环境变量管理
HTTP Server: 内置 HTTP 服务器，支持 MCP 协议

📁 项目结构

MCP-BTC-Watch/
├── src/
│   └── index.ts          # 主程序文件，包含所有核心逻辑
├── dist/                 # TypeScript 编译输出目录（构建后生成）
├── package.json          # 项目配置和依赖
├── tsconfig.json         # TypeScript 配置
├── bt-price.bat          # Windows 批处理文件（CLI 模式）
├── bt-price.sh           # Mac/Linux 启动脚本（CLI 模式）
├── mcp-launcher.bat      # Windows 批处理文件（MCP 服务器模式）
├── mcp-launcher.sh       # Mac/Linux 启动脚本（MCP 服务器模式）
├── LICENSE               # MIT 许可证
└── README.md             # 项目文档

📦 前置要求

Node.js: 版本 14.0 或更高
npm: 通常随 Node.js 一起安装
CoinMarketCap API Key (可选):
- 获取地址: pro.coinmarketcap.com
- 如果没有 API Key，系统会自动使用免费的 CoinGecko API

🚀 安装步骤

克隆仓库:

git clone https://github.com/your-username/MCP-BTC-Watch.git
cd MCP-BTC-Watch

安装依赖:
```
npm install
```
构建项目:
```
npm run build
```
构建完成后，TypeScript 代码将被编译到 dist/ 目录。

⚙️ 配置说明

环境变量配置

在项目根目录创建 .env 文件（如果不存在）:
```
touch .env
```
编辑 .env 文件，添加 CoinMarketCap API Key:
```
COINMARKETCAP_API_KEY=your_api_key_here
```
注意:
- 如果不提供 API Key，系统会自动使用 CoinGecko API（免费，无需 API Key）
- CoinMarketCap API 提供更稳定的服务，但需要注册账号
- CoinGecko API 是免费的，但有速率限制

服务器端口配置

默认端口为 3000，可以通过环境变量 PORT 自定义:

PORT=8080 npm start

💻 使用方法

CLI 模式（命令行工具）

直接运行编译后的文件：

# 使用 npm 脚本
npm start

# 或直接使用 node
node dist/index.js

Windows 用户可以使用提供的批处理文件：

bt-price.bat

Mac/Linux 用户可以使用提供的 Shell 脚本：

./bt-price.sh

或者使用 bash 命令：

bash bt-price.sh

CLI 模式会显示格式化的比特币价格信息，包括：

当前价格（USD）
24小时涨跌幅（带颜色标识）
市值
最后更新时间
数据来源

MCP 服务器模式

启动 MCP 服务器：

node dist/index.js --mcp-server

服务器启动后，将监听指定端口（默认 3000），并提供以下端点：

GET /: 返回 MCP 工具定义（JSON 格式）
GET /events: SSE 端点，用于 Cursor 等工具连接
GET /health: 健康检查端点
POST /execute: 执行工具请求

Windows 用户可以使用批处理文件：

mcp-launcher.bat

Mac/Linux 用户可以使用 Shell 脚本：

./mcp-launcher.sh

或者使用 bash 命令：

bash mcp-launcher.sh

注意: Windows 用户使用前需要修改 mcp-launcher.bat 中的路径为你的项目实际路径。Mac/Linux 脚本会自动使用当前目录，无需修改路径。

开发模式

使用 ts-node 直接运行 TypeScript 文件（无需先编译）：

npm run dev

🔌 集成指南

与 Claude Desktop 集成

定位 Claude Desktop 配置文件:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

添加配置:

{
  "mcpServers": {
    "btc-price": {
      "command": "node",
      "args": ["<FULL_PATH_TO_YOUR_PROJECT>/dist/index.js"],
      "env": {
        "COINMARKETCAP_API_KEY": "your-api-key-here"
      }
    }
  }
}

将 <FULL_PATH_TO_YOUR_PROJECT> 替换为项目的绝对路径。

示例:

Windows: C:/Users/YourName/Documents/MCP-BTC-Watch/dist/index.js
macOS/Linux: /Users/YourName/Documents/MCP-BTC-Watch/dist/index.js

重启 Claude Desktop 使配置生效。

与 Cursor 集成

快速开始：查看 QUICK_START.md 获取 5 分钟快速部署指南。

详细配置：查看 CURSOR_SETUP.md 获取完整的部署和配置说明。

快速步骤：

启动 MCP 服务器:
```
npm run mcp-server
```
配置 Cursor：
- 打开 Cursor 设置 (Ctrl+, 或 Cmd+,)
- 导航到 MCP 配置
- 添加服务器配置（参考 cursor-mcp-config.example.json）
- 确保允许 MCP 自动运行
重启 Cursor 并开始使用！

详细步骤请参考 CURSOR_SETUP.md。

在 Claude 中使用

配置完成后，你可以在 Claude 中询问：

"What's the current price of Bitcoin?"
"How much has Bitcoin changed in the last 24 hours?"
"What's the market cap of Bitcoin right now?"
"比特币现在的价格是多少？"
"比特币过去24小时涨了多少？"

🔧 开发说明

项目架构

项目采用单一文件架构，所有功能集中在 src/index.ts 中：

API 函数: getBitcoinPriceFromCMC() 和 getBitcoinPriceFromCoinGecko()
主函数: getBitcoinPrice() 实现自动回退逻辑
显示函数: displayBitcoinPrice() 格式化终端输出
MCP 定义: mcp 对象定义工具架构
服务器实现: HTTP 服务器处理 MCP 协议请求

添加新功能

要添加新的加密货币或功能：

在 src/index.ts 中添加新的 API 函数
更新 mcp.tools 对象，添加新工具定义
在服务器处理逻辑中添加对应的执行逻辑
重新构建项目: npm run build

调试

使用 npm run dev 进行开发，支持热重载
查看服务器日志了解请求详情
使用 /health 端点检查服务器状态

📡 API 文档

MCP 工具定义

`get-bitcoin-price`

获取比特币当前价格信息。

输入: 无参数

输出:

{
  "price": "string",              // 当前价格（USD）
  "percent_change_24h": "string", // 24小时涨跌幅（%）
  "market_cap": "string",         // 市值（USD）
  "last_updated": "string",       // 最后更新时间（ISO 8601）
  "source": "string"              // 数据来源（"CoinMarketCap" 或 "CoinGecko"）
}

HTTP 端点

`GET /`

返回 MCP 工具定义。

响应:

{
  "schemaVersion": "2.0",
  "tools": { ... }
}

`GET /events`

SSE 端点，用于 Cursor 等工具连接。发送初始工具定义后，定期发送心跳。

`GET /health`

健康检查端点。

响应:

{
  "status": "healthy"
}

`POST /execute`

执行工具请求。

请求体:

{
  "name": "get-bitcoin-price"
}

响应:

{
  "result": {
    "price": "...",
    "percent_change_24h": "...",
    "market_cap": "...",
    "last_updated": "...",
    "source": "..."
  }
}

📄 许可证

本项目采用 MIT 许可证。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📝 更新日志

v1.0.0

初始版本发布
支持 CoinMarketCap 和 CoinGecko API
实现 CLI 和 MCP 服务器模式
添加 SSE 支持
彩色终端输出

注意: 本项目是一个 MCP 服务器实现示例，展示了如何为 AI 工具提供实时数据访问能力。你可以基于此项目扩展更多功能，如支持其他加密货币、添加历史价格查询等。