CommodityPriceAPI

CommodityPriceAPI MCP 服务

CommodityPriceAPI 的官方 MCP 服务。提供 8 种 MCP 工具，用于查询实时和历史大宗商品价格，包括黄金、白银、石油、天然气、小麦、咖啡和 140 多种其他商品。你的 AI 助手可以用日常语言查询市场，MCP 服务则负责处理 API 调用。

适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Cline、Codex 以及任何其他兼容 MCP 的客户端。

项目	值
软件包	@commoditypriceapi/mcp
传输方式	stdio
Node.js	>=18

快速开始

1. 获取免费的 CommodityPriceAPI 密钥 — 免费试用 7 天，可发送 2,000 次请求，无需信用卡。

2. Cursor 用户可以一键安装：

   

3. 其他用户：将以下内容添加到 MCP 客户端配置中（确切的文件路径请参阅按客户端安装）：

{
  "mcpServers": {
    "commoditypriceapi": {
      "command": "npx",
      "args": ["-y", "@commoditypriceapi/mcp"],
      "env": {
        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

4. 重启客户端。

5. 测试：询问 “当前金价是多少？”

目录

• 快速开始
• 按客户端安装
• 验证是否正常运行
• 工具参考
• 提示词示例
• 回答和工具输出示例
• 错误代码
• 工作原理
• 环境变量
• 从源代码构建
• 故障排除
• 定价
• 链接
• 许可证

按客户端安装

要求

• Node.js 18 或更高版本
• 终端中可使用 npx
• CommodityPriceAPI 密钥 — 免费注册

Claude Desktop

将以下内容添加到 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "commoditypriceapi": {
      "command": "npx",
      "args": ["-y", "@commoditypriceapi/mcp"],
      "env": {
        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code

claude mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcp

添加服务后，启动新的 Claude Code 会话。

Cursor

一键安装：

或者手动将以下内容添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "commoditypriceapi": {
      "command": "npx",
      "args": ["-y", "@commoditypriceapi/mcp"],
      "env": {
        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Cursor。

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "commoditypriceapi": {
      "command": "npx",
      "args": ["-y", "@commoditypriceapi/mcp"],
      "env": {
        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Windsurf。

VS Code / GitHub Copilot

将以下内容添加到 VS Code 的 settings.json：

{
  "mcp": {
    "servers": {
      "commoditypriceapi": {
        "command": "npx",
        "args": ["-y", "@commoditypriceapi/mcp"],
        "env": {
          "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
        }
      }
    }
  }
}

保存后重启 VS Code。

Cline

打开 MCP Servers 面板 → Configure → Advanced MCP Settings。将以下内容添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "commoditypriceapi": {
      "command": "npx",
      "args": ["-y", "@commoditypriceapi/mcp"],
      "env": {
        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Cline。

Codex CLI

codex mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcp
codex mcp list

添加服务后，启动新的 Codex 会话。

其他 MCP 客户端

使用以下配置：

{
  "command": "npx",
  "args": ["-y", "@commoditypriceapi/mcp"],
  "env": {
    "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
  }
}

验证是否正常运行

完成设置后，试试以下提示词：

提示词	预期工具
当前金价是多少？	get_gold_price
获取最新的白银和布伦特原油价格。	get_latest_rates，参数为 symbols=XAG,BRENTOIL-SPOT
2020 年 1 月 2 日的金价是多少？	get_historical_rates
显示 2026 年 8 月第一周的每日金价。	get_time_series
2026 年 1 月到 8 月期间，金价变动了多少？	get_fluctuation
你支持哪些大宗商品代码？	list_symbols
我的 API 配额还剩多少？	get_usage

工具参考

全部 8 个工具与 CommodityPriceAPI v3 端点一一对应。接受 symbols 参数的工具支持以逗号分隔的代码列表（例如 XAU,XAG,XPT,BRENTOIL-SPOT）。使用 list_symbols 查询有效代码——共有 245 个，涵盖金属、能源、农业等类别。

贵金属使用 ISO 4217 代码：XAU（黄金）、XAG（白银）、XPT（铂金）、XPD（钯金）。铜的代码为 XCU。已停用的代码 PL、PA 和 HG 在 v3 中仍可用——它们会自动解析为新代码（见下方说明）。

get_latest_rates

GET /v3/rates/latest — 获取一个或多个代码的最新汇率。根据套餐不同，汇率可能最多延迟 10 分钟。

参数	必填	说明
symbols	是	以逗号分隔的代码，例如 XAU,XAG,BRENTOIL-SPOT
quote	否	目标报价货币（例如 EUR）。仅限 Premium/Plus 套餐；省略时使用每个代码的默认货币。
metadata	否	true（默认）或 false。false 会从响应中省略 metadata 映射（每个代码的单位和报价货币）。

关于 unresolved 的说明：在以下三种情况下，v3 会追加一个以你输入的代码为键的 unresolved 映射。get_historical_rates、get_time_series 和 get_fluctuation 也同样如此。

情况	HTTP	条目内容
代码不是目录中的代码，但恰好有一个匹配项（例如 GOLD 或已停用的 PL）	200	message + resolvedTo — 汇率会以 resolvedTo 为键返回在 rates 中。这仅供参考，并非失败。
部分代码无法返回	206	message + 可选的 suggestions（“你是否想找”）。有效汇率仍在 rates 中。
未能解析任何代码	404	工具会返回携带相同 unresolved 映射的 SYMBOL_NOT_FOUND 错误。

get_gold_price

GET /v3/rates/latest/xau — 快捷获取最新黄金（XAU）汇率，包括买入价/卖出价。

参数	必填	说明
quote	否	目标报价货币。仅限 Premium/Plus 套餐。
include	否	gram、carat 或 tola — 除盎司汇率外，还会添加每克汇率、24k 至 8k 各纯度的每克汇率，或每托拉汇率。
metadata	否	true（默认）或 false。false 会从响应中省略 metadata 映射（每个代码的单位和报价货币）。

get_silver_price

GET /v3/rates/latest/xag — 快捷获取最新白银（XAG）汇率，包括买入价/卖出价。

参数	必填	说明
quote	否	目标报价货币。仅限 Premium/Plus 套餐。
include	否	gram、carat 或 tola — 除盎司汇率外，还会添加每克、每克拉或每托拉汇率。
metadata	否	true（默认）或 false。false 会从响应中省略 metadata 映射（每个代码的单位和报价货币）。

get_historical_rates

GET /v3/rates/historical — 获取一个或多个代码在指定过去日期的开盘价/最高价/最低价/收盘价汇率，数据最早可追溯至 1990-01-01。如果该日期没有对应汇率，API 会返回最接近的可用日期。

参数	必填	说明
symbols	是	以逗号分隔的代码
date	是	YYYY-MM-DD

get_time_series

GET /v3/rates/time-series — 两个日期之间一个或多个符号的每日历史汇率。跨度最长为 1 年。

参数	必填	描述
symbols	是	以逗号分隔的符号
startDate	是	YYYY-MM-DD
endDate	是	YYYY-MM-DD

get_fluctuation

GET /v3/rates/fluctuation — 每个符号在两个日期之间的变化：起始汇率、结束汇率、绝对变化值和百分比变化。

参数	必填	描述
symbols	是	以逗号分隔的符号
startDate	是	YYYY-MM-DD
endDate	是	YYYY-MM-DD

list_symbols

GET /v3/symbols — 所有受支持的大宗商品符号，包括名称、类别、报价货币、单位和更新间隔。无需参数。不确定符号时，请在调用汇率工具前先调用此工具。

get_usage

GET /v3/usage — 已配置 API 密钥对应的当前套餐、配额和用量。无需参数。

提示词示例

实时价格

• 当前黄金价格是多少？
• 现在每克黄金多少钱？
• 获取白银、铂金、铜和 WTI 原油的最新价格。
• 黄金现在以欧元计价是多少？

历史数据

• 2026 年 1 月 2 日的小麦价格是多少？
• 比较过去 30 天的黄金和白银价格。
• 显示 2026 年第一季度的天然气每日价格。

价格变化

• 布伦特原油本季度波动了多少？
• 从年初到现在，黄金是涨了还是跌了？变化了多少？

发现与账户

• 你们支持哪些能源类大宗商品符号？
• 我这个月还剩多少 API 配额？

答案与工具输出示例

文本答案展示了客户端可能给出的回复；具体措辞取决于模型。JSON 代码块是原始工具输出。

最新黄金价格

提示词： 当前黄金价格是多少？

答案示例： 黄金（XAU）当前交易价为每金衡盎司 $4,386.23（买入价 $4,385.93 / 卖出价 $4,386.23）。

{
  "success": true,
  "timestamp": 1786617187,
  "rates": {
    "XAU": {
      "rate": 4386.23,
      "bid": 4385.93,
      "ask": 4386.23
    }
  },
  "metadata": {
    "XAU": {
      "unit": "T.oz",
      "quote": "USD"
    }
  }
}

历史汇率

提示词： 2020 年 1 月 2 日的黄金价格是多少？

答案示例： 2020-01-02，黄金开盘价为每金衡盎司 $1,518.26，收盘价为 $1,528.76（最高价 $1,531.31，最低价 $1,517.15）。

{
  "success": true,
  "date": "2020-01-02",
  "rates": {
    "XAU": {
      "date": "2020-01-02",
      "open": 1518.26,
      "high": 1531.31,
      "low": 1517.15,
      "close": 1528.76
    }
  }
}

波动情况

提示词： 2026 年 1 月 2 日至 8 月 12 日期间，黄金价格变化了多少？

答案示例： 黄金价格从每金衡盎司 $4,332.01 涨至 $4,400.12，上涨了 $68.11，即 +1.57%。

{
  "success": true,
  "startDate": "2026-01-02",
  "endDate": "2026-08-12",
  "rates": {
    "XAU": {
      "startRate": 4332.01,
      "endRate": 4400.12,
      "change": 68.11,
      "changePercent": 1.57
    }
  }
}

自动解析的符号

提示词： GOLD 和铂金的价格是多少？

答案示例： 黄金（XAU）为 $4,386.23，铂金（XPT）为每金衡盎司 $1,412.50。注意：GOLD 不是符号代码，因此 API 将其作为 XAU 返回。

{
  "success": true,
  "timestamp": 1786617187,
  "rates": {
    "XAU": 4386.23,
    "XPT": 1412.5
  },
  "metadata": {
    "XAU": { "unit": "T.oz", "quote": "USD" },
    "XPT": { "unit": "T.oz", "quote": "USD" }
  },
  "unresolved": {
    "GOLD": {
      "message": "GOLD is not a symbol code used by this API. Gold is available as \"XAU\", so its rate was returned under that symbol.",
      "resolvedTo": "XAU"
    }
  }
}

状态为 200 — 存在 resolvedTo 的条目不会降低响应状态。

错误代码

工具调用不会导致服务崩溃。上游错误会作为包含 error、code、message 和 guidance 字段的结构化工具结果返回，客户端可据此解释问题，而不是原样复述状态代码。

代码	含义
401	缺少或 API 密钥无效 — 检查客户端配置中的 COMMODITYPRICEAPI_KEY
402	当前试用版或订阅不支持此请求（例如，非 Premium 套餐下进行 quote 转换）
403	已达到 API 密钥用量限制 — 请升级或等待配额重置
404	未找到符号 — 调用 list_symbols 获取有效符号
429	请求受限 — 等待一分钟后重试
499	向上游 API 发送的请求超时（参见 COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS）
502	服务无法连接到上游 API

无效符号的错误结果示例：

{
  "error": "SYMBOL_NOT_FOUND",
  "code": 404,
  "message": "The symbol is not supported, please visit the documentation for a list of supported symbols",
  "guidance": "Call list_symbols to see valid commodity symbols."
}

工作原理

这是一个通过 stdio 封装 CommodityPriceAPI v3 REST API 的 MCP 服务。

运行时：

1. MCP 客户端通过 npx 启动服务进程。
2. 客户端读取工具列表。
3. 当提示词匹配某个工具时，客户端会调用该工具。
4. 服务会验证输入、调用 CommodityPriceAPI，并返回结构化 JSON。

服务会通过 x-api-key 标头和 apiKey 查询参数将你的 API 密钥发送给 CommodityPriceAPI。上游 API 接受其中任意一种方式，因此无需额外配置即可涵盖所有情况。

环境变量

变量	必填	默认值	描述
COMMODITYPRICEAPI_KEY	是		你的 CommodityPriceAPI 密钥
COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS	否	15000	上游请求超时时间，单位为 ms

从源代码构建

git clone https://github.com/Commodity-Price-API/commoditypriceapi-mcp.git
cd commoditypriceapi-mcp
npm install
npm run build

直接运行：

COMMODITYPRICEAPI_KEY=<YOUR_KEY> node dist/cli.js

使用 MCP Inspector 检查：

COMMODITYPRICEAPI_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

故障排除

客户端更新后仍使用旧工具列表： 重启客户端，并确认它加载了最新的 npm 版本。

401 错误： 检查 MCP 客户端配置的 env 块中是否设置了 COMMODITYPRICEAPI_KEY。

多符号响应中缺少某个符号： 查看结果中的 unresolved 映射。如果条目包含 resolvedTo，则并未缺少数据——对应汇率位于 rates 中的该符号下（例如，GOLD → XAU、PL → XPT）。否则，每个缺失的符号都会附带一条消息，通常还会有 suggestions（例如，OIL → WTIOIL-SPOT、BRENTOIL-SPOT、……）。如果没有建议，请调用 list_symbols 查找正确的符号。

499 超时： 上游 API 未能及时响应。请增大 COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS（默认值：15000 ms）。

定价

提供为期 7 天的免费试用，可发送 2,000 次请求，无需提供银行卡。有关套餐详情，请参阅 CommodityPriceAPI 定价页面。

链接

• CommodityPriceAPI 网站
• API 文档
• 支持的符号
• MCP 集成指南
• 定价
• 免费注册
• GitHub 仓库

许可证

MIT