内容
# 开放云成本 MCP 服务器
一个开源的 MCP 服务器，为 AI 助手提供准确的 AWS、GCP 和 Azure 云定价数据。
[](LICENSE)
[](https://pypi.org/project/opencloudcosts/)
[](https://github.com/x7even/cloudcostmcp/actions/workflows/tests.yml)
[](https://www.python.org/downloads/)
支持 **公共列表定价**（无需 AWS 和 Azure 凭证；GCP 需要免费 API 密钥）和 **实际（自定义私有定价协议）费率**（折扣后：预留实例、节省计划、CUD、EDP）。
## 关键用例
- “在 us-east-1 和 ap-southeast-2 中，m5.xlarge 的按需价格是多少，delta 百分比是多少？”
- “为以下架构提供 TCO 估算：3x m5.xlarge + 1x 500GB gp3 EBS in us-east-1”
- “如果我运行此堆栈 50,000 MAUs，每个用户的成本是多少？”
- “列出 eu-west-1 中所有 c6g 实例，vCPU >= 8”
- “在节省计划后，m5.xlarge 的有效小时费率是多少？”
## 工具（v0.9.0 — 15 个工具）
**定价**
| 工具 | 描述 |
|------|-------------|
| `get_price` | 统一定价调度器 — 计算、存储、数据库、AI、网络、Serverless、分析、监控 |
| `get_prices_batch` | 一次调用中获取多个实例类型的价格（并发） |
| `compare_prices` | 比较多个区域的规格，可选基准 delta |
| `search_pricing` | 跨定价目录的自由文本搜索 |
**发现**
| 工具 | 描述 |
|------|-------------|
| `describe_catalog` | 完整支持矩阵或目标字段指导 + `get_price` 的复制粘贴 `example_invocation` |
| `list_regions` | 所有区域的友好名称 |
| `list_instance_types` | 可用的实例类型，带有 vCPU/内存过滤器 |
**区域分析**
| 工具 | 描述 |
|------|-------------|
| `find_cheapest_region` | 任何服务规格的最便宜区域，并发 |
| `find_available_regions` | 服务可用的每个区域，按价格排序 |
| `get_spot_history` | AWS Spot 价格历史和稳定性分析（需要凭证） |
**FinOps**
| 工具 | 描述 |
|------|-------------|
| `get_discount_summary` | 账户范围的 RI / 节省计划 / CUD 利用率（需要凭证） |
| `estimate_bom` | 多资源物料清单的 TCO |
| `estimate_unit_economics` | 每用户/请求/事务的成本 |
**缓存**
| 工具 | 描述 |
|------|-------------|
| `refresh_cache` | 使定价缓存失效 |
| `cache_stats` | 缓存条目计数和数据库大小 |
查看 [docs/tools.md](docs/tools.md) 获取完整的参数引用和 [docs/finops-guide.md](docs/finops-guide.md) 获取使用示例。
## 安装
### 快速安装（推荐）
```bash
# 直接从 PyPI 运行，无需克隆
uvx opencloudcosts
# 或永久安装
pip install opencloudcosts
opencloudcosts
```
### 先决条件（开发/基于克隆的安装）
- 安装 [uv](https://docs.astral.sh/uv/) （`curl -LsSf https://astral.sh/uv/install.sh | sh`）
- AWS 凭证（可选 — 公共定价无需凭证）
### 克隆和配置
```bash
git clone https://github.com/x7even/cloudcostmcp opencloudcosts
cd opencloudcosts
cp .env.example .env
# 编辑 .env 以获取有效定价 / 成本浏览器
```
### 测试它是否有效
```bash
uv run pytest
```
### 运行服务器
```bash
uv run opencloudcosts
```
### 作为 HTTP 服务器运行
HTTP 传输启用共享/远程部署 — 一个服务器，多个客户端。
```bash
# 仅限本地主机（默认）
uv run opencloudcosts --transport http --port 8080
# 绑定到所有接口（例如 Docker 或远程访问）
uv run opencloudcosts --transport http --host 0.0.0.0 --port 8080
```
环境变量等效项：`OCC_HTTP_HOST` 和 `OCC_HTTP_PORT`。
通过 `.mcp.json` 连接到 Claude Code：
```json
{
"mcpServers": {
"cloudcost": {
"transport": "http",
"url": "http://localhost:8080/mcp/v1"
}
}
}
```
### Docker
```bash
# 从注册表拉取（推荐）
docker pull ghcr.io/x7even/opencloudcosts:latest
docker run -p 8080:8080 \
-e OCC_GCP_API_KEY=AIza... \
-v ~/.aws:/root/.aws:ro \
ghcr.io/x7even/opencloudcosts:latest
# 或本地构建
docker build -t opencloudcosts .
docker run -p 8080:8080 opencloudcosts
```
容器默认以 HTTP 传输模式启动（绑定到 `0.0.0.0:8080`）。
通过 `-e` 标志传递云凭证或挂载您的 AWS 凭证目录。
### 连接到 Claude Code
添加到您项目的 `.mcp.json`：
```json
{
"mcpServers": {
"cloudcost": {
"command": "uv",
"args": ["run", "--directory", "/path/to/opencloudcosts", "opencloudcosts"],
"env": {
"AWS_PROFILE": "default",
"OCC_GCP_API_KEY": "AIza..."
}
}
}
}
```
或全局访问添加到 `~/.claude/settings.json`：
```json
{
"mcpServers": {
"cloudcost": {
"command": "uv",
"args": ["run", "--directory", "/path/to/opencloudcosts", "opencloudcosts"]
}
}
}
```
### 使用 MCP Inspector 测试
```bash
npx @modelcontextprotocol/inspector uv run --directory /path/to/opencloudcosts opencloudcosts
```
## AWS 凭证
| 功能 | 需要凭证 |
|---------|--------------------|
| 公共定价（EC2、EBS、RDS 列表价格） | 无 |
| 有效定价（RI / SP 折扣） | AWS 凭证 + `OCC_AWS_ENABLE_COST_EXPLORER=true` |
最低 IAM 策略用于公共定价：
```json
{
"Effect": "Allow",
"Action": ["pricing:GetProducts", "pricing:DescribeServices", "pricing:GetAttributeValues"],
"Resource": "*"
}
```
添加以下内容以获取有效定价：
```json
"ce:GetCostAndUsage", "savingsplans:DescribeSavingsPlans", "savingsplans:DescribeSavingsPlanRates"
```
## 配置
所有设置均通过环境变量（前缀 `OCC_`）或 `.env` 文件：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `OCC_CACHE_TTL_HOURS` | 24 | 公共价格缓存 TTL |
| `OCC_AWS_ENABLE_COST_EXPLORER` | false | 启用 AWS 有效定价（费用 $0.01/次调用） |
| `OCC_DEFAULT_REGIONS` | us-east-1,us-west-2 | 默认区域 |
| `AWS_PROFILE` | （默认链） | AWS 凭证配置文件 |
| `OCC_GCP_BILLING_ACCOUNT_ID` | （无） | GCP 结算账户 ID，用于合同/有效定价 |
## 缓存
价格缓存在 `~/.cache/opencloudcosts/pricing.db` 中的 SQLite 中。公共列表价格缓存 24 小时 — AWS 定价变化不频繁。使用 `refresh_cache` 工具强制刷新。
## GCP 设置
与 AWS 不同（AWS 有公共批量定价端点），GCP 的定价 API 始终需要至少一个免费 API 密钥。不需要信用卡或结算账户。
**选项 A — 免费 API 密钥（推荐，2 分钟设置）：**
1. 前往 [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
2. 创建一个项目（如果您没有一个）
3. 点击 **创建凭证 → API 密钥**
4. 设置密钥：
```bash
export OCC_GCP_API_KEY=AIza...
```
或将 `OCC_GCP_API_KEY=AIza...` 添加到您的 `.env` 文件中。
**选项 B — 应用程序默认凭证**（如果您已经使用 `gcloud`）：
```bash
gcloud auth application-default login
# 或设置 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```
**GCP 实例类型格式：** `{family}-{series}-{vcpus}` 例如 `n2-standard-4`、`e2-highmem-8`、`c2-standard-16`
### GCP 合同 / 有效定价
如果您与 Google Cloud 有协商的定价合同，您可以通过 Cloud Billing Pricing API v1beta 获取您的实际折扣费率（EDP，自定义定价）。这需要：
1. ADC 凭证：`gcloud auth application-default login`
2. `billing.billingAccountPrice.get` IAM 权限您的结算账户
3. 您的结算账户 ID：
```bash
export OCC_GCP_BILLING_ACCOUNT_ID=012345-567890-ABCDEF
```
配置完成后，GCP 计算的 `get_price` 响应将包括一个 `effective_price` 块，显示您的合同费率和折扣百分比。没有它，公共列表价格将保持不变。
## Azure 设置
Azure 定价是完全公开的 — 无需凭证、API 密钥或订阅。
```bash
# 无需配置 — 开箱即用
uv run opencloudcosts
```
**Azure 实例类型格式：** ARM SKU 名称，例如 `Standard_D4s_v3`、`Standard_E8s_v3`、`Standard_B2ms`
**Azure 定价条款：** `on_demand`（默认）、`reserved_1yr`、`reserved_3yr`、`spot`
**Azure 区域：** ARM 区域名称，例如 `eastus`、`westeurope`、`southeastasia`（使用 `list_regions` 获取完整列表）
**Azure 支持的服务（v0.8.12）：**
| 领域 | 服务 | 描述 |
|--------|---------|-------------|
| compute | vm | 虚拟机 — 所有系列、Linux/Windows、按需/现货/预留 |
| storage | managed_disks | 高级 SSD、标准 SSD、标准 HDD、超磁盘 |
| storage | blob | Blob 存储 |
| database | sql | Azure SQL 数据库、Azure DB for MySQL/PostgreSQL — vCore 层、HA、预留 |
| database | cosmos | Cosmos DB — 预置（每 100 RU/s）、无服务器、自动缩放 |
| container | aks | AKS 集群管理费（免费层或 $0.10/小时标准） |
| serverless | azure_functions | 函数消耗计划 — 每 GB-秒 + 每次执行 |
| ai | openai | Azure OpenAI — GPT-4o、GPT-4、GPT-3.5-Turbo、o1、嵌入式 |
| inter_region_egress | — | 出站数据传输 — 互联网和区域间，区域 1 费率，5 GB/月免费 |
**GCP 定价条款：** `on_demand`（默认）、`spot`（可中断）、`cud_1yr`、`cud_3yr`
## 安全
OpenCloudCosts 可以在配置了云凭证时访问敏感的计费数据。请遵循以下准则来保护这些数据的安全。
**凭证卫生**
- 使用专用、最小权限凭证 — 仅限定价和计费 API 的只读访问权限。永远不要使用根、所有者或管理员凭证。
- AWS：创建具有 `ce:GetCostAndUsage`、`pricing:GetProducts` 和 `savingsplans:Describe*` 权限的 IAM 用户/角色。
- 将凭证存储在 `.env` 中（参见 `.env.example`），并永远不要将该文件提交到版本控制中。
**传输安全**
- 默认的 `stdio` 传输是安全的 — 服务器作为本地进程运行，没有网络暴露。
- 如果您使用 `--transport http`，请永远不要在没有反向代理和身份验证的情况下公开暴露它。请将其视为内部服务。
**MCP 客户端信任**
- 仅将此服务器添加到您控制的 MCP 客户端配置中。
- 避免与不受信任的第三方 MCP 服务器一起运行 — 恶意服务器可以构造提示，引起 LLM 调用您的计费工具并中继结果。
**此服务器可以访问的内容**
配置凭证后：实际支出、合同/协商定价、预留和节省计划数据。在共享或多用户环境中授予访问权限之前，请了解这些信息。
## 阶段
- **阶段 1** ✅ AWS 公共定价（EC2、EBS、列表实例）
- **阶段 2** ✅ AWS 有效定价（成本浏览器、节省计划、预留实例）
- **阶段 3** ✅ GCP 公共定价（Compute Engine 系列、持久磁盘、CUD）
- **阶段 4** ✅ Azure 公共定价（零售价格 API，无凭证）
- **阶段 4** ✅ 可流式 HTTP 传输（`--transport http`）、Dockerfile
- **阶段 4** ✅ Spot 价格历史工具（`get_spot_history`）、GCP Windows 定价
- **阶段 5** ✅ GCP 管理服务 — GKE、Memorystore、BigQuery、Vertex AI、Gemini
- **阶段 5** ✅ GCP 网络 — Cloud LB、CDN、NAT、Cloud Armor、Cloud Monitoring
- **阶段 5** ✅ GCP Cloud SQL；Azure 预留定价
- **v0.8.0** ✅ 整合为 15 工具表面；统一 `get_price(spec)` 调度器；`describe_catalog` 发现；123/123（100%）测试套件通过率
- **v0.8.2** ✅ 提供者协议清理 — `major_regions()`、`default_region()`、`bom_advisories()` 在所有提供者上；工具层中没有提供者字符串条件
- **v0.8.3** ✅ `NormalizedPrice` 上的信任元数据（`fetched_at`、`source_url`、`cache_age_seconds`）；区域间出口域 + AWS 数据传输定价
- **v0.8.4** ✅ 数值价格字段 — 结构化 `{amount, unit, currency, display}` 字典替换所有工具边界上的格式化字符串
- **v0.8.5** ✅ 服务→域推理（`fill_domain`）；结构化 `invalid_spec` 错误提示；123/123 测试套件（高于 84%）
- **v0.8.8** ✅ Azure 广度：SQL 数据库、Cosmos DB、AKS、Azure Functions、Azure OpenAI；151/151 测试套件（28 个新测试场景）
- **v0.8.9** ✅ 通过 Cloud Billing Pricing API v1beta 进行 GCP 有效/合同定价（`OCC_GCP_BILLING_ACCOUNT_ID`）；GCP 现已与 AWS 有效定价保持一致
- **v0.8.10** ✅ `GcpAuthProvider` — 多源 OAuth（SA JSON B64、WIF、ADC、元数据服务器、原始令牌）；`google-auth[requests]` 可选 `[gcp]` 额外；事件循环安全刷新；容器中无需 gcloud
- **v0.8.11** ✅ GCP 存储和数据库合同定价 — GCS、持久磁盘、Cloud SQL（所有引擎/大小/HA）、Memorystore；`effective_price` 在 `StoragePricingSpec` 和 `DatabasePricingSpec` 上，当配置了结算账户
- **v0.8.12** ✅ Azure 出口定价（`inter_region_egress` 域）— 互联网和区域间出站传输，区域 1 费率来自零售价格 API，5 GB/月免费层，响应中的每月估算
- **v0.8.13** ✅ GCP 网络合同定价 — Cloud LB、CDN、NAT、Cloud Armor；`effective_price` 在 `NetworkPricingSpec` 上，当配置了结算账户
- **v0.8.14** ✅ GCP 互联网和区域间出口（`inter_region_egress` 域）— 基于大陆的费率来自 SKU 目录，静态备用；跨云出口比较现已跨 AWS、GCP 和 Azure 工作
- **v0.9.1** ✅ GCP 出口合同定价 — 配置结算账户时 `effective_price` 在互联网出口上；修复 `PricingResult.source` Literal 以包含 `"catalog+billing_api"`
