内容
# xe-mcp
一款适用于 [Xe 货币数据 API](https://www.xe.com/xecurrencydata/) 的 MCP 服务器 — 将实时外汇汇率、历史分析和量化工具直接带入 Claude Code、Claude Desktop 和任何兼容 MCP 的 AI 工具中。
**无需凭证即可开箱即用** — 自动回落到 Frankfurter（欧洲央行数据）。插入 Xe API 密钥即可切换到 Xe 的实时数据。所有 12 种工具均无需凭证。
---
## 工具列表
| 工具 | 功能 |
|---|---|
| `get_rate` | 任意两种货币之间的实时中间汇率 |
| `convert` | 按当前汇率转换金额 |
| `list_currencies` | 常用货币（内置）；使用 Xe 密钥可获取完整 Xe 列表（约 170 种货币） |
| `get_historical_rates` | 货币对在 N 天内的每日汇率 |
| `volatility_analysis` | 每日标准差 + 年化波动率 — 对数收益率方法（外汇期权标准） |
| `optimal_send_window` | 今日汇率在 N 天分布中的百分位排名 + 判决 |
| `nzd_corridors` | NZD 在 USD、AUD、EUR、GBP、JPY、SGD、CNY 中的快照 |
| `correlation_analysis` | 两个货币对之间的日对数收益率的皮尔逊相关系数 |
| `rate_alert_check` | 检查汇率是否超过阈值 — 返回触发：是/否 + 距离 |
| `rate_chart` | 终端中货币对汇率历史的 ASCII 行图 |
| `moving_average` | 简单移动平均线（20/50/200）及当前汇率和与每条平均线的距离百分比 |
| `pair_summary` | 一键晨间简报：汇率 + 范围 + 波动率 + 发送判决 + 简单移动平均线（20） |
---
## 实时输出示例
以下所有示例均使用 Frankfurter/ECB — 无需 API 密钥。
```
> get_rate NZD USD
1 NZD = 0.564940 USD (Frankfurter/ECB, 2026-06-26)
> optimal_send_window NZD USD
NZD→USD 发送窗口（Frankfurter/ECB）
当前汇率： 0.564940
30 日均值： 0.580598
30 日范围： 0.563860 – 0.597400
百分位： 第 14 位（历史 21 天中有 3 天更低）
判决： 不利 — 底部四分位数
时间戳： 2026-06-26
> moving_average NZD USD
NZD/USD — 移动平均线（Frankfurter/ECB）
当前汇率： 0.564940
简单移动平均线（20）： 0.579758 （当前比平均线低 2.56%）
简单移动平均线（50）： 数据不足（需要 50 天，有 36 天）
> volatility_analysis NZD USD 30
NZD/USD — 30 日波动率（Frankfurter/ECB）
当前汇率： 0.564940
范围（30 天）： 0.563860 – 0.597400
每日波动率： 0.4023%
年化波动率： 6.39%
使用数据点： 21
> correlation_analysis NZD USD AUD USD 30
相关性：NZD/USD vs AUD/USD（Frankfurter/ECB，30 天）
皮尔逊相关系数： 0.8553
解释： 强正相关
数据点： 20 个对齐交易日
> rate_chart NZD USD 30
NZD/USD — 过去 30 个交易日（Frankfurter/ECB）
0.5974 │●●
│ ●●
│ ●●●
│ ●●
0.5806 │ ●●│ │
│ ●●│
│ ●│
│ ●│
0.5639 │ ●●●
└─────────────────────
05-29 06-12 06-26
```
---
## 安装
### 无凭证模式（Frankfurter/ECB）
所有 11 种工具均可在无需 API 密钥的情况下，使用 Frankfurter 通过 [Frankfurter](https://www.frankfurter.app/) 提供的免费欧洲央行数据。`list_currencies` 返回一个内置的常用货币列表；使用 Xe 凭证可返回完整的约 170 种货币列表。
```bash
git clone https://github.com/CedricConday/xe-mcp
cd xe-mcp
npm install && npm run build
```
添加到 Claude Code：
```bash
claude mcp add xe-mcp node /path/to/xe-mcp/dist/index.js
```
### 使用 Xe API（实时汇率）
在 [xe.com/xecurrencydata](https://www.xe.com/xecurrencydata/) 获取凭证，然后：
```bash
claude mcp add xe-mcp node /path/to/xe-mcp/dist/index.js \
-e XE_ACCOUNT_ID=your_account_id \
-e XE_API_KEY=your_api_key
```
或添加到 `.claude/settings.json`：
```json
{
"mcpServers": {
"xe-mcp": {
"command": "node",
"args": ["/path/to/xe-mcp/dist/index.js"],
"env": {
"XE_ACCOUNT_ID": "your_account_id",
"XE_API_KEY": "your_api_key"
}
}
}
}
```
### Claude Code 斜杠命令
此仓库附带一个 `/fx` 命令，用于快速分析。将以下内容添加到您的项目中：
```bash
cp -r .claude/commands /your-project/.claude/
```
然后使用 `/fx NZDUSD`、`/fx NZDUSD vol`、`/fx convert 1000 NZD USD`。
---
## 架构
### 本地（MCP 标准输入/输出服务器）
```
Claude Code ↔ 标准输入/输出 ↔ xe-mcp ──→ Xe XECD API（如果有凭证）
└→ Frankfurter/ECB（免费备用）
```
```
xe-mcp/
├── src/
│ ├── index.ts # MCP 服务器（标准输入/输出传输）
│ ├── xe-client.ts # Xe XECD API 包装器（身份验证）
│ ├── frankfurter-client.ts # Frankfurter ECB API（免费备用）
│ ├── s3-cache.ts # S3 支持的汇率历史缓存（Lambda 使用）
│ └── tools/
│ ├── rates.ts # get_rate, convert, list_currencies
│ ├── analysis.ts # get_historical_rates, volatility_analysis, optimal_send_window
│ ├── nzd.ts # nzd_corridors
│ ├── correlation.ts # correlation_analysis
│ ├── alerts.ts # rate_alert_check
│ └── chart.ts # rate_chart（ASCII）
├── lambda/
│ ├── handler.ts # REST Lambda — 所有 10 种工具通过 POST /tool/{name}
│ ├── alert-scheduler.ts # CloudWatch 每小时 → DynamoDB 扫描 → SQS 发布
│ └── alert-processor.ts # SQS 消费者 → SES 电子邮件通知
├── src/__tests__/ # 49 个单元测试（5 个测试套件）
├── .github/workflows/
│ ├── ci.yml # 测试 → 构建 → 推送后验证
│ └── deploy.yml # 测试 → 构建 → 部署到 AWS（ap-southeast-2）
├── Dockerfile # 多阶段 Alpine — 本地和 ECS/K8s 部署
└── template.yml # SAM：Lambda + API Gateway + SQS + DynamoDB + S3
```
### AWS 部署（`sam deploy`）
```
API Gateway → handler Lambda → Xe/Frankfurter → 响应
CloudWatch Events（每小时）→ alert-scheduler Lambda → DynamoDB → SQS
↓
alert-processor Lambda → SES 电子邮件
DynamoDB：警报配置（userId, from, to, threshold, direction）
S3：汇率历史缓存桶（在 src/s3-cache.ts 中初始化；尚未连接到处理程序）
```
**凭证检测：** 环境中的 `XE_ACCOUNT_ID` + `XE_API_KEY` → Xe。否则 → Frankfurter。Lambda 和本地环境中均有相同的备用机制。
---
## 堆栈覆盖
构建以匹配 Xe.com 开发人员职位描述中列出的全栈需求。下面列表中的每一项都由此仓库中的代码支持（S3 缓存已初始化但尚未连接 — 如下所述）。
| 需求 | 所在位置 |
|---|---|
| TypeScript | `src/`、`lambda/` — 完整代码库 |
| MCP / 代理工具 | `src/index.ts` — 标准输入/输出传输，12 种注册工具 |
| AWS Lambda | `lambda/handler.ts` — 所有 10 种工具的 REST API |
| AWS SQS | `lambda/alert-scheduler.ts` → 发布；`lambda/alert-processor.ts` → 消费 |
| AWS DynamoDB | `lambda/alert-scheduler.ts` — 扫描 `AlertsTable`；SAM 在 `userId` 上具有 GSI |
| AWS S3 | `src/s3-cache.ts` — 汇率历史缓存模块 + `template.yml` 中的存储桶（初始化；尚未连接到已部署的处理程序） |
| SQLite（本地） | `src/sqlite-store.ts` — 汇率历史缓存（`RATE_DB_PATH`）；实时在 `fetchHistoricalSeries` — 缓存命中跳过 API，错过存储到 DB；相同的架构适用于 PostgreSQL |
| AWS SES | `lambda/alert-processor.ts` — 在警报触发时发送电子邮件 |
| AWS API Gateway | `template.yml` — 连接到 `XeMcpFunction` |
| CloudWatch Events | `template.yml` — `AlertSchedulerFunction` 的每小时调度触发器 |
| SAM / IaC | `template.yml` — 完整堆栈即代码，`sam build && sam deploy` |
| CI/CD（GitHub Actions） | `.github/workflows/ci.yml` — 测试 → 构建 → 验证；`deploy.yml` — 部署到 ap-southeast-2 |
| Docker | `Dockerfile` — 多阶段 Alpine 构建，用于 ECS / 本地环境 |
| 外汇领域知识 | `optimal_send_window`、`volatility_analysis`、`correlation_analysis` — 对数收益率方法 |
---
## 测试
```bash
npm test
# 测试套件：5 通过
# 测试： 49 通过
```
测试覆盖：零波动率边缘情况、恒定收益率序列、年化波动率公式（× √252）、百分位分布、皮尔逊 r 属性（完美相关性、逆相关性、零方差）、NZD/AUD 协动性健全性、SMA 计算（周期排序、边缘情况、与 SMA 的距离）、SQLite 架构（主键约束、更新行为、范围查询排序、索引验证）、pair_summary 数学（百分位排名、判决标签、SMA(20) 边界）。
---
## 为什么
Xe 的开发人员职位发布要求“每天使用代理编码工具（Claude Code 或等效工具）”。我构建了我希望在 Xe 的外汇数据管道中使用的工具 — 一个将汇率情报带入编码环境而无需切换到选项卡的工具。
量化工具 (`volatility_analysis`、`optimal_send_window`、`correlation_analysis`) 来自货币市场经验。它们不是股票分析库的包装器；数学是直接的对数收益率方法，并有测试覆盖。
---
## 技术栈
TypeScript · Node.js · `@modelcontextprotocol/sdk` · Xe XECD API · Frankfurter API
## 许可证
MIT
