coingecko-mcp-server

---

概述

通过 CoinGecko 获取加密货币市场数据——涵盖 15,000 多种币的价格、排名、历史图表和详细资料。将名称或代码解析为 CoinGecko 的 slug 键 ID，然后依次查询价格、排名市场和趋势图表。

工具

工具	描述
coingecko_search_coins	将币种名称或代码解析为 CoinGecko ID（slug）。这是使用任何以 ID 为键的工具前必须执行的步骤。
coingecko_get_prices	批量获取多种币及货币的当前价格和核心市场统计数据。
coingecko_list_markets	排名市场表——按市值、交易量或 ID 排列币种；也可按类别或指定 ID 筛选。
coingecko_get_coin	单个币种的详细资料——描述、链接、市场数据、开发者活动、社区和情绪。使用 sections 缩减较大的记录。
coingecko_get_market_chart	历史价格、市值和交易量序列。支持 recent 模式（最近 N 天，自动确定粒度）或 range 模式（指定 Unix 秒时间范围）。
coingecko_get_trending	按搜索量列出过去 24 小时内在 CoinGecko 上热度上升的币种。
coingecko_get_global	全球加密货币市场快照——总市值和交易量、BTC/ETH 市场占比、活跃数量、进行中的 ICO 及 24 小时变化。
coingecko_list_categories	币种类别（category_id + 显示名称）——即 coingecko_list_markets 的 category 筛选器所接受的有效 slug。

资源

资源	描述
coingecko://coin/{id}	按 slug 查询币种的详细记录——数据与 coingecko_get_coin 相同（完整记录、美元市场数据）。
coingecko://global	全球加密货币市场快照——数据与 coingecko_get_global 相同。

所有资源数据也可通过工具获取——这些资源与 coingecko_get_coin 和 coingecko_get_global 完全一致，因此仅使用工具的客户端不会损失任何数据。大型集合（市场、类别）不会作为资源公开；请改用 coingecko_list_markets 和 coingecko_list_categories。

提示词

提示词	描述
coingecko_coin_research	引导用户完成单个币种的完整研究流程，依次调用 search → get_coin → get_market_chart → get_global。

功能参考

coingecko_search_coins _tool

• Ticker 并非唯一标识（许多币种共用 ETH/USDC）——返回按相关性排序的候选项，并提供 id、symbol、name 和 marketCapRank 以便区分
• 返回相关性最高的 25 个匹配项；当列表受限时，enrichment.truncated 以及 shown/cap 会说明这一点
• 搜索结果为空是正常情况，并非错误——enrichment.notice 会建议扩大查询范围

---

coingecko_get_prices _tool

• 最多接受 500 个原始 ID（会去除首尾空格、转为小写并去重），并处理前 250 个唯一 slug；其余 ID 会列在 skippedIds 中，未找到的 ID 会列在 missing 中，因为未知 slug 会返回空的上游响应，而非错误
• 每个返回价格的 (id, currency) 对应一行；市值、24 小时交易量和 24 小时涨跌幅均为可选字段。没有报价的货币会在 enrichment.notice 中说明
• lastUpdatedAtUnixSec 使用 Unix 秒；coingecko_get_market_chart 的数据点时间戳则使用毫秒
• 若请求的 ID 均未找到，则抛出 all_missing；若 ID 已找到，但没有任何请求的货币返回数值报价，则抛出 no_price_data

---

coingecko_list_markets _tool

• 通过 order 按市值、交易量或 ID 升序或降序排序；使用 page 和 per_page 分页（默认 50 行，最多 250 行）
• 可按 ids 筛选（与价格批次相同，最多 500 个原始 ID/250 个唯一 ID；appliedIds 和 skippedIds 会显示所选 ID），也可按 category 筛选（使用 coingecko_list_categories 返回的 categoryId），但不能同时使用两者——同时使用会返回 conflicting_filters
• 每个币种的字段包括价格、市值、交易量、1 小时/24 小时/7 天涨跌幅、供应量以及 ATH/ATL；完整页面会由 enrichment.truncated 标记
• 若 CoinGecko 对按类别筛选的请求返回 HTTP 404，则抛出 unknown_category

---

coingecko_get_coin _tool

• 包含六个部分——profile、market、links、developer、community、sentiment；sections 可将响应裁剪为仅包含所需内容（完整记录很大）
• 价格和百分比涨跌幅时间窗口使用 vs_currency（默认值为 usd）；上游缺失的字段会被省略，而不会伪造
• profile.categories 是展示名称（例如 "Layer 1 (L1)"），与 coingecko_list_categories 返回的 categoryId slug 不同
• 若上游无法识别该 slug，则抛出 coin_not_found；若请求的市场货币不受支持，则抛出 unsupported_currency

---

coingecko_get_market_chart _工具

• recent 模式接受 1–365 天（"max" 是 365 天窗口的别名，并会发出提示）；range 模式接受作为 Unix 秒数的 from/to
• interval 可选择 auto（上游默认值）、daily 或 hourly，具体取决于上游层级和窗口可用性
• 使用 point_offset（默认值为 0）和 point_limit（默认值为 100，上限为 250）分页；每个系列的总数和 nextPointOffset 支持继续获取，且每一页都会重新获取上游数据
• granularity 用 5-minute、hourly、daily、irregular 或 unknown 表示系列间隔；点的时间戳为 Unix 毫秒，而 coingecko_get_prices 的 lastUpdatedAtUnixSec 为秒
• 模式与参数不匹配时抛出 invalid_range；无法识别 slug 时抛出 coin_not_found

---

coingecko_get_trending _工具

• 无参数 — 返回 24 小时内按搜索量排名的热门币种；有数据时，每个币种均包含 marketCapRank、priceUsd、priceBtc 和 priceChangePercentage24hUsd
• 上游将市值和交易量报告为预先格式化的显示字符串，而非数字 — 因此会省略这些字段，不将其呈现为数值数据
• nftCount 报告上游同时返回的热门 NFT 数量；不会展示 NFT 详情

---

coingecko_get_global _工具

• 无需币种 ID — 一次调用即可获取宏观概览
• vs_currency（默认值为 usd）仅限定总市值和交易量；上游始终以 USD 为单位报告市值占比和 24 小时变化百分比
• 当请求的货币在上游的逐币种映射中没有对应条目时，抛出 unsupported_currency — /global 不会进行上游货币验证，因此未知代码会静默地不返回总额
• 返回活跃加密货币数量、活跃市场数量、正在进行的 ICO 数量，以及以 Unix 秒为单位的快照时间戳

---

coingecko_list_categories _工具

• 可选的 name_contains 按空白分隔的词元进行筛选，不区分大小写和标点；名称必须包含所有词元
• enrichment.totalCount 报告筛选前的类别总数；筛选结果为空时会返回 enrichment.notice
• 返回的 categoryId 值可用于 coingecko_list_markets 的 category 参数

---

coingecko://coin/{id} _资源

• 数据与 coingecko_get_coin 的完整记录相同，始终以 USD 为单位
• {id} 是 CoinGecko slug（例如 "bitcoin"）— 使用 coingecko_search_coins 解析代号
• 上游无法识别该 slug 时抛出 coin_not_found

---

coingecko://global _资源

• 数据与 coingecko_get_global 相同，始终以 USD 为单位
• 无参数

---

coingecko_coin_research _提示词

• 参数：必填的 coin — 名称、代号或 CoinGecko slug
• 返回一条用于构建助手对话的消息，以及一条引导完成 search → get_coin → get_market_chart → get_global 流程的用户消息

功能特性

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

CoinGecko 专属功能：

• 为 CoinGecko v3 REST API 提供类型安全的客户端，每个端点对应一个服务方法
• 可在公共层级免密运行；可选的 Demo API 密钥（x-cg-demo-api-key）可提高速率上限，无需更改其他配置
• 针对速率限制、上游暂时性故障和超时进行重试与退避；遵循 Retry-After，永久性拒绝则立即失败
• 根据状态码提供错误原因和恢复提示，包括在受限历史时间范围内缩小查询范围

便于 Agent 使用的输出：

• 通过描述强制要求先搜索再查询——每个以 ID 为键的工具都会注明应使用 slug 而非 ticker，并指向 coingecko_search_coins
• 部分读取——价格结果会披露未解析的 ID 和没有报价的货币；补充数据会披露市值和已应用的筛选条件
• 明确单位——时间戳字段会注明单位是秒还是毫秒
• 每个工具和资源输出均附带 CoinGecko 要求的署名；研究提示词会指示 Agent 以相同方式注明其发现的来源

开始使用

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥——只有在需要使用更高的 CoinGecko Demo 层级时，才设置 COINGECKO_API_KEY（参见配置）。

{
  "mcpServers": {
    "coingecko-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/coingecko-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "coingecko-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/coingecko-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "coingecko-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/coingecko-mcp-server:latest"
      ]
    }
  }
}

要添加 CoinGecko Demo 密钥，请在 env 块中添加 "COINGECKO_API_KEY": "your-demo-key"（Docker 则使用 -e COINGECKO_API_KEY=your-demo-key）。

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 运行无需账户或 API 密钥。也可选用免费的 CoinGecko Demo API 密钥，以获得高于共享免密公共池的速率上限（每月 10k 次调用，每分钟 100 req）。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/coingecko-mcp-server.git

2. 进入目录：

cd coingecko-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# the server runs with no .env at all; edit only to set COINGECKO_API_KEY

配置

服务无需任何配置即可运行。唯一的服务专属变量为可选项：

变量	描述	默认值
COINGECKO_API_KEY	可选的 CoinGecko Demo API 密钥，将作为 x-cg-demo-api-key 标头发送（每月 10k 次，每分钟 100 req）。未设置 → 使用免密公共层级。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 埋点（跨度、指标、完成日志）。	false

完整的可选覆盖项列表见 .env.example。

速率限制与数据新鲜度。 免密公共层级使用共享的 IP 限流资源池，因此在负载较低时，突发的多工具工作流也可能触发 429；服务会退避并重试，但无法提高上限——免费 Demo 密钥则可以。CoinGecko 数据大约每 60 秒刷新一次，并非逐笔更新。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t coingecko-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 coingecko-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/coingecko-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具、资源和提示词，并初始化 CoinGecko 服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。
src/services/coingecko	CoinGecko v3 REST API 服务——HTTP 客户端、重试与错误映射、响应规范化、领域类型。
tests/	与 src/ 目录结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/index.ts 中的 createApp() 数组注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；不要伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。