Numbeo API MCP服务器🌍
FastMCP服务器包装 API公司，提供有关生活成本、房价和犯罪率的数据。
建筑
此存储库包含两个Python包：
📦 numbeo-sdk
Numbeo SDK是用于Numbeo API的独立Python客户端库。它处理所有HTTP通信，并提供一个干净的接口来访问Numbeo数据。
🖥️ numbeo-mcp
Numbeo MCP服务器是一个FastMCP服务器，它将SDK功能作为MCP工具公开，具有：
- 严格验证 使用Pydantic模式
- 承载令牌身份验证 -客户端提供并传播到SDK的API密钥
- 词汇资源 -解释Numbeo API术语
- 10个MCP工具 -涵盖所有主要Numbeo端点
特性
- 🏙️ 生活成本数据：获取城市和国家的当前和历史价格
- 🏠 房价：获取房地产市场数据
- 🚨 犯罪统计：检索安全和犯罪指数
- 📊 城市指数：比较生活质量、医疗保健、交通和污染指标
- 🏆 排名：全球和国家特定城市排名
- 🔐 安全认证：从MCP客户端传递到SDK的API密钥
入门指南
先决条件
- Python 3.12或更高版本
- Numbeo API密钥（从 API公司)
安装
安装软件包：
pip install -e .或使用紫外线：
uv sync运行MCP服务器
启动MCP服务器：
numbeo-mcp服务器将启动并公开10个MCP工具和一个词汇资源。
认证
MCP服务器希望API密钥由客户端通过以下方式之一提供：
api_key请求元数据中的字段Authorization: Bearer头球
API密钥不由MCP服务器验证，但传播到Numbeo SDK，后者在API调用中使用它。
身份验证流程：
MCP Client → MCP Server → Numbeo SDK → Numbeo API
(Bearer) (propagate) (use in query params)可用的MCP工具
生活工具成本
get_city_cost_of_living
获取一个城市商品和服务的当前价格。
参数：
city（字符串，必填）：城市名称（例如，“纽约”、“伦敦”）country（字符串，可选）：用于消除歧义的国家名称
例子：
{
"city": "New York",
"country": "United States"
}get_city_cost_of_living_archive
获取历史生活成本数据以进行趋势分析。
参数：
city（string，必填）：城市名称country（字符串，可选）：国家名称currency（字符串，可选）：货币代码（例如“USD”、“EUR”）
get_city_indices
获取包括生活成本、租金、杂货和购买力在内的综合指数。
参数：
city（string，必填）：城市名称country（字符串，可选）：国家名称
get_country_prices
获取国家层面的平均价格。
参数：
country（string，必填）：国家名称
生活质量工具
get_city_healthcare
获取医疗质量和可及性指数。
参数：
city（string，必填）：城市名称country（字符串，可选）：国家名称
get_city_traffic
获取交通状况和通勤时间数据。
参数：
city（string，必填）：城市名称country（字符串，可选）：国家名称
get_city_pollution
获取空气质量和环境指数。
参数：
city（string，必填）：城市名称country（字符串，可选）：国家名称
安全工具
get_city_crime_statistics
获取犯罪率和安全感知指数。
参数：
city（string，必填）：城市名称country（字符串，可选）：国家名称
排名工具
get_city_rankings
获取不同类别的全球城市排名。
参数：
section（字符串，可选，默认值：“生活成本”）：排名类别
- "cost-of-living"：总生活费 - "crime"：安全等级 - "health-care"：医疗质量 - "pollution"：环境质量 - "traffic"：交通和通勤 - "quality-of-life"：整体生活质量
get_country_city_rankings
获取特定国家的城市排名。
参数：
country（string，必填）：国家名称section（字符串，可选）：与相同的选项get_city_rankings
词汇资源
服务器提供 vocabulary://numbeo-terms 解释Numbeo API响应中使用的术语的资源：
contributors12months：过去12个月内提交数据的贡献者人数monthLastUpdate：上次更新数据的月份yearLastUpdate：上次更新的年份contributors：在计算中使用其数据的贡献者总数（适应性档案政策）cpi_factor：用于计算我们的消费者价格指数的一个因素。将该系数乘以价格，并将结果加到总金额中，以计算生活成本指数rent_factor：用于计算我们租金指数的一个因素。将该系数乘以价格，并将结果加到总和中，以计算租金指数
与MCP客户端一起使用
克劳德桌面
MCP客户端应通过请求元数据或授权头提供API密钥。配置示例：
{
"mcpServers": {
"numbeo": {
"command": "numbeo-mcp"
}
}
}然后通过客户端的授权机制在工具调用中传递API密钥。
其他MCP客户端
服务器支持stdio上的标准MCP协议。API密钥应通过：
- 请求元数据(
api_key字段），或 - 授权标头(
Authorization: Bearer)
直接使用SDK
你也可以直接在Python代码中使用Numbeo SDK：
import asyncio
from numbeo_sdk import Numbeo, modeling
async def main() -> None:
async with Numbeo(key="your-api-key") as client:
prices = await client.get_city_prices(
modeling.GetCityPricesRequest(city="London", country="United Kingdom")
)
print(prices.model_dump(by_alias=True))
crime = await client.get_city_crime(
modeling.GetCityCrimeRequest(city="Tokyo", country="Japan")
)
print(crime.model_dump(by_alias=True))
rankings = await client.get_rankings_by_city_current(
modeling.GetRankingsByCityCurrentRequest(section=1)
)
print([entry.model_dump(by_alias=True) for entry in rankings.root])
asyncio.run(main())发展
设置
make sync代码检查
make linting格式化
make style运行测试
make test出口要求
make export封装结构
src/
├── numbeo_sdk/ # Numbeo API SDK
│ ├── __init__.py
│ └── client.py # HTTP client for Numbeo API
└── numbeo_mcp/ # FastMCP server
├── __init__.py
├── server.py # MCP server with tools
└── schemas.py # Pydantic validation schemas验证
MCP服务器使用 严格的输入验证 使用Pydantic模式。所有工具参数在传递给SDK之前都经过验证：
- 城市查询参数：城市（必填），国家（可选）
- 城市档案查询参数：城市、国家、货币（均已验证）
- 排名查询参数：带有枚举验证的部分
- 还有更多。..
无效的输入将被拒绝，并显示明确的错误消息。
api参考
此服务器包装Numbeo API终结点。有关返回数据的详细信息，请参阅 Numbeo API文档.
主要特点：
- 所有SDK请求都包含API密钥作为查询参数
- MCP服务器使用Pydantic进行严格的输入验证
- 无需身份验证标头（来自客户端的承载令牌→ SDK)
- 返回包含全面城市/国家统计数据的JSON数据
API费率限制
Numbeo API可能有费率限制，具体取决于您的订阅级别。参见 Numbeo API文件 了解详情。
故障排除
“需要Numbeo API密钥”错误
API密钥必须由MCP客户端通过授权头或请求元数据提供，而不是通过环境变量提供。检查您的MCP客户端配置。
连接超时
检查您的互联网连接，并验证Numbeo API是否可访问。
API响应无效
请确保您的API密钥有效，并且您的订阅处于活动状态。
验证错误
服务器使用严格的Pydantic验证。确保所有必填字段都已提供，枚举值正确（例如，section必须是以下之一：“生活成本”、“犯罪”、“医疗保健”、“污染”、“交通”、“生活质量”）。
许可证
看 许可证 文件以获取详细信息。