Metadata-Version: 2.4
Name: mcp-exchange-master
Version: 0.1.0
Summary: 汇率全能 MCP Server — 实时汇率/留学预算/跨境定价/结汇建议, 支持28种货币
Author: Exchange Master Team
License-Expression: MIT
License-File: LICENSE
Keywords: cross-border,currency,exchange-rate,forex,mcp,study-abroad
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.9.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 💱 mcp-exchange-master

**汇率全能 MCP Server** — 实时汇率查询、留学预算、跨境电商定价、结汇时机建议，一个 Server 全搞定。

合并自 4 个扣子技能：汇率精算师 / 汇率计算 / 留学汇率精算师 / 跨境电商汇率卫士。

数据源：[TianAPI](https://www.tianapi.com/) 中国银行外汇牌价，支持 28 种主流货币。

---

## 🛠 工具列表

| 工具 | 功能 | 典型场景 |
|------|------|---------|
| `exchange_rate` | 实时汇率查询 + 双向换算 | "美元兑人民币多少" "1000英镑换多少人民币" |
| `exchange_history` | 历史汇率走势 + 趋势判断 | "最近美元走势如何" "欧元涨还是跌" |
| `study_abroad_budget` | 留学费用预算 + 汇率换算 | "美国留学一年要多少钱" "5万美元学费换多少人民币" |
| `cross_border_pricing` | 跨境电商多站点定价 | "成本50元的产品在美国站卖多少" |
| `settlement_advice` | 结汇时机建议 | "有1万美元要结汇,现在合适吗" |

---

## 📦 安装

```bash
pip install mcp-exchange-master
```

或从源码安装：

```bash
git clone https://github.com/yourname/mcp-exchange-master.git
cd mcp-exchange-master
pip install -e .
```

## ⚙️ 配置

需要 [TianAPI](https://www.tianapi.com/) API 密钥（免费注册即得）：

```bash
export TIANAPI_KEY="your_api_key_here"
```

## 🚀 使用

### 命令行

```bash
# STDIO 模式 (默认)
mcp-exchange-master

# 或
python -m mcp_exchange_master
```

### MCP 客户端配置

在 Claude Desktop / Cherry Studio / ChatBox 等 MCP 客户端中添加：

```json
{
  "mcpServers": {
    "exchange-master": {
      "command": "mcp-exchange-master",
      "env": {
        "TIANAPI_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 开发测试

```bash
# 安装 FastMCP CLI
pip install "mcp[cli]"

# 交互式测试
mcp dev src/mcp_exchange_master/server.py

# 检查工具列表
mcp inspect src/mcp_exchange_master/server.py
```

## 💡 工具详细说明

### exchange_rate — 实时汇率 + 换算

```python
# 查汇率
exchange_rate(from_currency="USD", to_currency="CNY")

# 换算金额
exchange_rate(from_currency="USD", to_currency="CNY", amount=5000)

# 双向汇率
exchange_rate(from_currency="美元", to_currency="人民币", bidirectional=True)
```

支持口语化输入：美元/美金/刀/英镑/人民币/块 等。

### study_abroad_budget — 留学预算

```python
study_abroad_budget(
    target_country="美国",
    tuition=50000,
    tuition_currency="USD",
    living_cost_monthly=2000,
    duration_years=2,
    home_currency="CNY"
)
```

返回学费/生活费换算、年度预算、汇率波动风险区间。

### cross_border_pricing — 跨境定价

```python
cross_border_pricing(
    cost_cny=50,
    target_profit_rate=0.3,
    currencies="USD,EUR,GBP,JPY",
    platform_rate=0.15,
    safety_buffer=0.05
)
```

返回各币种建议售价、实际利润率、平台费用。

### settlement_advice — 结汇建议

```python
settlement_advice(
    currency="USD",
    amount=10000,
    bank="boc"
)
```

返回银行牌价、结汇建议(立即/部分/观望/暂缓)、建议比例。

## 🌍 支持货币 (28种)

CNY USD EUR GBP JPY HKD KRW AUD CAD THB CHF SGD NZD MYR PHP RUB IDR SEK NOK DKK INR AED SAR BRL MOP ZAR TRY

## 📄 许可证

MIT License

---

# 💱 mcp-exchange-master (English)

**All-in-One Exchange Rate MCP Server** — Real-time rates, study abroad budget, cross-border pricing, and settlement advice.

Merged from 4 Coze skills into a single FastMCP Server, powered by [TianAPI](https://www.tianapi.com/) (Bank of China forex rates), supporting 28 currencies.

## Tools

| Tool | Description |
|------|-------------|
| `exchange_rate` | Real-time exchange rate query + bidirectional conversion |
| `exchange_history` | Historical rate trends + direction analysis |
| `study_abroad_budget` | Study abroad cost budgeting + currency conversion |
| `cross_border_pricing` | Cross-border e-commerce multi-currency pricing |
| `settlement_advice` | Forex settlement timing advice based on bank rates |

## Install

```bash
pip install mcp-exchange-master
```

## Configure

```bash
export TIANAPI_KEY="your_api_key"  # Free at tianapi.com
```

## MCP Client Config

```json
{
  "mcpServers": {
    "exchange-master": {
      "command": "mcp-exchange-master",
      "env": {
        "TIANAPI_KEY": "your_api_key"
      }
    }
  }
}
```

## License

MIT
