Crypto Price Tracker MCP Server

加密货币价格追踪 MCP 服务

一个基于 Python 的服务应用，可让用户追踪加密货币价格、管理关注列表，并将数据导出到 Google Sheets。此服务使用 FastMCP 框架构建，设计为使用 Docker 运行的容器化应用。

目录

• 加密货币价格追踪 MCP 服务
  • 目录
  • 功能
  • 技术栈
  • 前置条件
  • 安装
    • 1. 克隆代码库
    • 2. 创建并激活 Python 虚拟环境
    • 3. 安装依赖项
    • 4. 获取 Google Sheets API 凭据
    • 5. 构建 Docker 镜像
    • 6. 运行 Docker 容器
      • 直接使用 Docker
      • 配置参数
      • MCP 客户端集成（GitHub Copilot）
      • 前置条件
      • 设置配置
  • 工作原理
  • 配置
  • 用法
    • 可用工具
      • 使用提示词生成工具
  • 数据持久化
  • 贡献
  • 许可证

功能

• 关注列表管理：
  • 将加密货币添加到个人关注列表。
  • 从关注列表中移除加密货币。
  • 查看当前关注列表。
• 价格追踪：
  • 获取关注列表中所有币种的最新价格（使用 CoinGecko API）。
• Google Sheets 集成：
  • 将关注列表和价格数据导出到 Google 表格。
  • 与指定用户共享 Google 表格。
  • 根据 Google 表格中的数据分析表现（最高涨幅/跌幅）。
• MCP 交互：
  • 通过 stdio 上的 MCP（模型上下文协议）提供用于交互的工具和提示词。

技术栈

• Python 3.12+
• **Docker：**用于容器化。
• **FastMCP（mcp[cli]）：**用于构建服务及其工具的框架。
• **uv：**用于 Docker 构建过程中的 Python 包管理。
• **httpx：**用于向加密货币 API 发送 HTTP 请求。
• **Google API 客户端库：**用于与 Google Sheets 交互。
  • google-api-python-client
  • google-auth
  • google-auth-oauthlib
  • google-auth-httplib2

前置条件

• **Docker：**必须已安装并运行。安装 Docker
• **Google Cloud 项目和服务账号：**Google Sheets 集成所需。
  • 一个 Google Cloud Platform 项目。
  • 已为该项目启用 Google Sheets API。
  • 一个具有编辑 Google Sheets 权限的服务账号。
  • 服务账号的 JSON 密钥文件（称为 google_credentials.json）。

安装

1. 克隆代码库

首先，将此代码库克隆到本地计算机：

git clone [email protected]:RoystonDAlmeida/crypto-price-tracker-mcp.git
cd crypto-price-tracker-mcp/

2. 创建并激活 Python 虚拟环境

强烈建议使用虚拟环境隔离项目依赖项。本项目需要 Python 3.12+。

# Navigate to your project directory if you aren't already there
# cd crypto-price-tracker-mcp/

# Create a virtual environment (e.g., named .venv)
python3.12 -m venv .venv

# Activate the virtual environment:
# On macOS and Linux:
source .venv/bin/activate
# On Windows (Git Bash or WSL):
# source .venv/Scripts/activate
# On Windows (Command Prompt):
# .venv\Scripts\activate.bat
# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1

激活后，shell 提示符应显示当前激活的环境（例如 (.venv)）。

3. 安装依赖项

本项目使用 uv 管理 Python 包（如“技术栈”中所述，并在 Dockerfile 中使用），依赖项定义在 pyproject.toml 中。确保虚拟环境已激活，且当前位于项目根目录，然后运行：

# Ensure uv is installed (e.g., pip install uv, or follow uv's installation guide)
# Then, install the project in editable mode with its dependencies:
uv pip install -e .

这将把 crypto-price-tracker-mcp 包及其所需库安装到虚拟环境中。

4. 获取 Google Sheets API 凭据

1. 前往 Google Cloud Console。
2. 创建新项目或选择现有项目。
3. 为项目启用“Google Sheets API”。
4. 创建服务账号：

• 前往“IAM & Admin” > “Service Accounts”。
• 点击“Create Service Account”。
• 为其命名（例如，“crypto-sheets-editor”）。
• 点击“Done”。

5. 为服务账号创建 JSON 密钥：

• 在列表中找到新创建的服务账号。
• 点击其旁边的三点图标（Actions），然后选择“Manage keys”。
• 点击“Add Key” > “Create new key”。
• 选择“JSON”作为密钥类型，然后点击“Create”。
• 系统会下载一个 JSON 文件。将此文件重命名为 google_credentials.json。将此文件添加到项目文件夹的根目录。

5. 构建 Docker 镜像

在虚拟环境中，导航到项目的根目录（Dockerfile 所在位置）并运行：

docker build -t crypto-price-tracker .

6. 运行 Docker 容器

要运行服务，需要将 google_credentials.json 文件挂载到容器中。

直接使用 Docker

docker run -it --rm \
  -v /path/to/your/local/google_credentials.json:/app/google_credentials.json \
  crypto-price-tracker

将 /path/to/your/local/google_credentials.json 替换为主机上 google_credentials.json 文件的实际绝对路径。

配置参数

-it：以交互模式运行容器并分配 TTY，这是进行 stdio 通信所必需的。 --rm：容器退出时自动将其移除。 -v ...：将本地凭据文件挂载到容器内的 /app/google_credentials.json，应用默认会在此处查找该文件。

MCP 客户端集成（GitHub Copilot）

由于我们将通过在 MCP 客户端（GitHub Copilot）中输入提示词来与此容器化 MCP 服务交互，请将以下配置添加到 VSCode 的 settings.json（打开用户设置文件）中：

{
    "mcpServers": {
        "crypto-price-tracker": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-v",
                "<local_path>/google_credentials.json:/app/google_credentials.json",
                "-e",
                "GOOGLE_CREDENTIALS_PATH=/app/google_credentials.json",
                "crypto-price-tracker-mcp"
            ]
        }
    }
}

以 Agent 模式启动 Github Copilot，它会启动 settings.json 中指定的服务。检查控制台输出，确认工具已成功发现。

前提条件

请务必先使用正确的标签构建 Docker 镜像：

docker build -t crypto-price-tracker-mcp .

设置配置

重要说明：

• 将 <local_path> 替换为主机上 google_credentials.json 文件的实际绝对路径。
• MCP 客户端集成通常使用 -i 标志（而非 -it），因为通常只需要标准输入（stdin），而不需要完整的 TTY。
• 示例中明确设置了环境变量 GOOGLE_CREDENTIALS_PATH，以确保容器内的应用知道凭据文件的位置。
• **通信方式：**服务通过 stdio（标准输入/标准输出）通信，因此可以与 GitHub Copilot 等 MCP 客户端无缝集成。

工作原理

服务通过 stdio（标准输入/标准输出）通信，因此可以与 GitHub Copilot 等 MCP 客户端兼容。这样，你就可以通过自然语言提示词与容器化的 MCP 服务交互，同时由服务在后台处理加密货币价格跟踪和 Google Sheets 集成。

将 /path/to/your/local/google_credentials.json 替换为主机上 google_credentials.json 文件的实际绝对路径。

• -it：以交互模式运行容器并分配 TTY，这是进行 stdio 通信所必需的。
• --rm：容器退出时自动将其移除。
• -v ...：将本地凭据文件挂载到容器内的 /app/google_credentials.json，应用默认会在此处查找该文件。

服务通过 stdio（标准输入/标准输出）通信。你可以使用 MCP 客户端（Github Copilot）与其交互。

配置

• Google 凭据：
  • 默认情况下，应用会在容器内的 /app/google_credentials.json 查找 Google Sheets API 凭据。
  • 运行容器时，可通过设置 GOOGLE_CREDENTIALS_PATH 环境变量覆盖此路径（例如，-e GOOGLE_CREDENTIALS_PATH=/custom/path/creds.json）。

用法

服务通过 stdio 使用 MCP 协议运行。启动容器后，即可接受 MCP 请求。

可用工具

服务提供了多个可调用的工具：

• get_watchlist：获取当前跟踪的加密货币列表。
• add_to_watchlist(id: str)：将一种加密货币（例如，“bitcoin”）添加到列表中。
• remove_from_watchlist(id: str)：从列表中移除一种加密货币。
• fetch_prices：获取列表中所有币种的最新价格。
• export_to_sheets(sheet_name: str, user_email: str)：将所有跟踪的价格数据导出到指定 sheet_name 的 Google Sheet，并与 user_email 分享。
• get_sheet_performance_leaders(sheet_name: str)：根据“Change_24h”列，识别指定 Google Sheet 中涨幅最高和跌幅最大的加密货币。

使用提示词生成工具

为了帮助 MCP 客户端（如 GitHub Copilot）拟定请求或向用户建议操作，服务还提供了几个“提示词生成”工具。这些工具在调用后会返回自然语言字符串。以下是这些工具、生成的提示词及其用途概览：

• get_watchlist_prompt()

  • 生成的提示词（返回的响应）："Please fetch the watchlist."
  • 调用的工具（确认后）：get_watchlist
  • 用途：建议或启动检索并显示用户当前的观察列表。

• add_coin_prompt(coin_id: str)

  • 输入示例：coin_id="ethereum"
  • 生成的提示词（返回的响应）："Please add ETHEREUM to my watchlist."
  • 调用的工具（确认后）：add_to_watchlist（使用指定的 coin_id）
  • 用途：帮助拟定将特定加密货币添加到观察列表的请求。

• remove_coin_prompt(coin_id: str)

  • 输入示例：coin_id="bitcoin"
  • 生成的提示词（返回的响应）："Please remove bitcoin from my watchlist."
  • 调用的工具（确认后）：remove_from_watchlist（使用指定的 coin_id）
  • 用途：帮助拟定从观察列表中移除特定加密货币的请求。

• get_prices_prompt()

  • 生成的提示词（返回的响应）："Please fetch the latest prices for all cryptocurrencies in my watchlist."
  • 调用的工具（确认后）：fetch_prices
  • 用途：发起请求，更新并显示观察列表中所有币种的当前市场价格。

• export_prompt(sheet_name: str, user_email: str)

  • 输入示例：sheet_name="Crypto Portfolio"、user_email="[email protected]"
  • 生成的提示词（返回的响应）："Please export all tracked price data to my Google Sheet 'Crypto Portfolio' and share it with [email protected]."
  • 调用的工具（确认后）：export_to_sheets（使用 sheet_name 和 user_email）
  • 用途：便于请求将观察列表和价格数据导出到 Google Sheet 并分享。

• get_sheet_performance_leaders_prompt(sheet_name: str)

  • 输入示例：sheet_name="Crypto Analysis"
  • 生成的提示词（返回的响应）："From the Google Sheet named 'Crypto Analysis', can you tell me which crypto had the highest gain and which one had the biggest loss recently?"
  • 调用的工具（确认后）：get_sheet_performance_leaders（使用 sheet_name）
  • 用途：帮助请求对指定 Google Sheet 中的表现进行分析（涨幅最高／跌幅最大）。

MCP 客户端通常会使用这些生成的提示词来引导用户，或在用户确认后直接拟定对某个主要操作工具（如 add_to_watchlist(id: str)、get_watchlist() 等）的调用。

数据持久化

• watchlist.json：
  • 用户的观察列表存储在名为 watchlist.json 的文件中。
  • 在 Docker 容器内，此文件将在 /app/watchlist.json 创建。

贡献

欢迎并非常感谢您贡献代码！如果您想为此项目做出贡献，请遵循以下一般步骤：

1. Fork 仓库： 首先，将主仓库 Fork 到您自己的 GitHub 账户。

2. 克隆您的 Fork： 将您 Fork 的仓库克隆到本地计算机：

   git clone https://github.com/YOUR_USERNAME/crypto-price-tracker-mcp.git
   cd crypto-price-tracker-mcp
   

3. 设置开发环境： 按照安装步骤设置本地开发环境，包括创建虚拟环境和安装依赖项。

4. 创建新分支： 为您的功能或错误修复创建一个新分支。请使用描述性名称（例如，feature/add-new-exchange 或 fix/price-fetch-error）。

   git checkout -b your-branch-name
   

5. 进行更改： 实现您的功能或修复错误。确保代码符合项目的编码风格和规范。

6. 测试更改： （如适用）为您的更改添加或更新测试，并确保所有测试都通过。

7. 提交更改： 使用清晰简洁的提交消息提交更改。

   git add .
   git commit -m "feat: Describe your feature or fix"
   

   （可以考虑使用 Conventional Commits 编写提交消息。）

8. 推送到您的 Fork： 将更改推送到 GitHub 上您 Fork 的仓库。

   git push origin your-branch-name
   

9. 创建拉取请求（PR）： 前往 GitHub 上的原始仓库，从您 Fork 的分支向主仓库的 main（或 master）分支创建拉取请求。在 PR 中清晰地描述您的更改。

许可证

本项目采用 MIT License 许可。