内容
# GoldAPI.io MCP 服务器
GoldAPI.io 的官方模型上下文协议服务器，用于提供贵金属数据。
`@goldapi/mcp-server` 允许 MCP 客户端，如 Claude Desktop、ChatGPT、Cursor、Windsurf 等 AI 代理运行时，从 GoldAPI.io 获取实时和历史的贵金属价格，并进行常见的金银和珠宝价值计算。
## 功能
- 提供最新的 GoldAPI.io 现货价格，包括黄金、白银、铂金和钯金。
- 按日期提供历史 GoldAPI 价格。
- 根据重量、单位和纯度计算金属价值。
- 支持主要法定货币和 BTC。
- 严格的输入验证，并提供有用的 MCP 错误信息。
## 安装
```bash
npm install -g @goldapi/mcp-server
```
您也可以在不进行全局安装的情况下运行：
```bash
npx -y @goldapi/mcp-server
```
## 环境
从 GoldAPI 仪表板创建 GoldAPI API 密钥，并将其作为 `GOLDAPI_KEY` 环境变量传递。
```bash
GOLDAPI_KEY=您的_api_key
```
如果缺少 `GOLDAPI_KEY`，服务器将退出，并显示以下信息：
```text
缺少 GOLDAPI_KEY 环境变量
```
## Claude Desktop 配置
将以下内容添加到您的 Claude Desktop MCP 配置中：
```json
{
"mcpServers": {
"goldapi": {
"command": "npx",
"args": ["-y", "@goldapi/mcp-server"],
"env": {
"GOLDAPI_KEY": "您的_api_key"
}
}
}
}
```
## Cursor 设置
在 Cursor 设置中添加新的 MCP 服务器：
```json
{
"mcpServers": {
"goldapi": {
"command": "npx",
"args": ["-y", "@goldapi/mcp-server"],
"env": {
"GOLDAPI_KEY": "您的_api_key"
}
}
}
}
```
## Windsurf 设置
将服务器添加到您的 Windsurf MCP 配置中：
```json
{
"mcpServers": {
"goldapi": {
"command": "npx",
"args": ["-y", "@goldapi/mcp-server"],
"env": {
"GOLDAPI_KEY": "您的_api_key"
}
}
}
}
```
## 工具
### `get_metal_price`
获取最新的贵金属现货价格。
输入：
```json
{
"metal": "XAU",
"currency": "USD"
}
```
输出：
```json
{
"metal": "XAU",
"currency": "USD",
"price": 2391.72,
"change": 11.6,
"changePercent": 0.49,
"timestamp": 1716000000
}
```
### `get_historical_metal_price`
获取历史金属价格。
输入：
```json
{
"metal": "XAU",
"currency": "USD",
"date": "20250101"
}
```
调用：
```text
GET https://www.goldapi.io/api/{metal}/{currency}/{date}
```
### `calculate_metal_value`
根据重量和纯度计算金属价值。
输入：
```json
{
"metal": "XAU",
"currency": "AED",
"weight": 125,
"unit": "gram",
"purity": "22k"
}
```
输出：
```json
{
"metal": "XAU",
"metalName": "黄金",
"currency": "AED",
"weight": 125,
"unit": "gram",
"purity": "22k",
"purityPercent": 91.67,
"spotPricePerGram": 283.21,
"adjustedPricePerGram": 259.57,
"totalValue": 32446.25,
"timestamp": 1716000000,
"humanReadable": "当前估计的 125 克 22k 黄金价值为 AED 32,446.25。"
}
```
支持的单位：
- `gram`
- `kg`
- `oz`
- `troy_oz`
支持的纯度：
- `24k` = 100%
- `22k` = 91.67%
- `21k` = 87.5%
- `20k` = 83.33%
- `18k` = 75%
- `16k` = 66.67%
- `14k` = 58.33%
- `10k` = 41.67%
### `get_supported_metals`
返回：
```json
["XAU", "XAG", "XPT", "XPD"]
```
### `get_supported_currencies`
返回所有支持的货币。
## 支持的金属
- `XAU` - 黄金
- `XAG` - 白银
- `XPT` - 铂金
- `XPD` - 钯金
## 支持的货币
```text
AED, AUD, BTC, CAD, CHF, CNY, CZK, EGP, EUR, GBP, HKD, INR, JOD, JPY, KRW, KWD, MXN, MYR, OMR, PLN, RUB, SAR, SGD, THB, USD, ZAR
```
## 示例提示
```text
黄金价格是多少（AUD）？
```
```text
125 克 22k 黄金在 AED 中的当前价值是多少？
```
```text
2025 年 1 月 1 日黄金价格（USD）是多少？
```
```text
3 个金衡盎司白银的价值是多少？
```
## 本地开发
```bash
npm install
npm run build
npm run verify
```
在本地运行服务器：
```bash
GOLDAPI_KEY=您的_api_key npm run dev
```
运行已构建的服务器：
```bash
GOLDAPI_KEY=您的_api_key npm start
```
## 发布
```bash
npm publish --access public
```
