JinDaGe - google-air-quality-mcp MCP Details

article

README

🚀 Google空气质量MCP服务器

Google空气质量MCP服务器是一个模型上下文协议（MCP）服务器，它提供对Google空气质量API的访问，使AI助手能够检索实时空气质量数据、预报、历史信息和热图可视化。

🚀 快速开始

前提条件

Go 1.21或更高版本
Google空气质量API密钥（请参阅API密钥设置）

安装步骤

克隆仓库

git clone git@github.com:ContexaAI/google-air-quality-mcp.git
cd google-air-quality-mcp

安装依赖项

go mod download

配置环境变量

在项目根目录下创建一个.env文件：

GOOGLE_AIR_QUALITY_API_KEY=your_api_key_here
MCP_SERVER_NAME=Google Air Quality MCP Server
PORT=8080

运行服务器

go run cmd/server/main.go

服务器将在http://localhost:8080启动，MCP端点位于/mcp。

使用MCP检查器连接

打开MCP检查器
连接到http://localhost:8080/mcp
探索可用的工具、提示和资源

✨ 主要特性

🌍 实时空气质量数据 - 全球任何地点的当前空气质量状况
📊 预报 - 每小时的空气质量预测
📈 历史数据 - 访问过去的空气质量测量值
🗺️ 热图可视化 - 生成空气质量热图切片
🤖 对大语言模型友好的提示 - 支持自然语言位置查询
📦 MCP资源 - 通过URI模板访问结构化数据

📦 安装指南

克隆仓库

git clone git@github.com:ContexaAI/google-air-quality-mcp.git
cd google-air-quality-mcp

安装依赖项

go mod download

配置环境变量

在项目根目录下创建.env文件，并按如下示例配置：

GOOGLE_AIR_QUALITY_API_KEY=your_api_key_here
MCP_SERVER_NAME=Google Air Quality MCP Server
PORT=8080

💻 使用示例

使用工具

获取旧金山的当前空气质量：

{
  "name": "get_current_air_quality",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "universalAqi": true
  }
}

获取纽约的24小时空气质量预报：

{
  "name": "get_air_quality_forecast",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "pageSize": 24
  }
}

获取伦敦的历史空气质量数据：

{
  "name": "get_air_quality_history",
  "arguments": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "hours": 72
  }
}

使用提示

提示允许你使用自然语言位置名称，大语言模型将自动将其解析为坐标。

提示使用示例：

Use the current_air_quality_by_location_prompt with location "Tokyo, Japan"

大语言模型将执行以下操作：

将“东京，日本”解析为坐标 (35.6762, 139.6503)
使用这些坐标调用get_current_air_quality工具
返回空气质量数据

使用资源

读取服务器信息：

URI: example://server-info

这将返回有关服务器和可用资源的基本信息。

📚 详细文档

API密钥设置

步骤1：启用API

访问Google Cloud控制台
创建一个新项目或选择一个现有项目
导航到API和服务 > 库
搜索“空气质量API”
点击启用

步骤2：创建API凭证

转到API和服务 > 凭证
点击创建凭证 > API密钥
复制生成的API密钥
（建议）点击限制密钥并进行以下设置：
- 在API限制下，选择“限制密钥”
- 从下拉菜单中选择“空气质量API”
- 在应用程序限制下，你可以按IP、HTTP引用等进行限制

步骤3：配置服务器

将你的API密钥添加到.env文件中：

GOOGLE_AIR_QUALITY_API_KEY=AIzaSyD...your-key-here

⚠️ 重要提示

空气质量API可能要求在你的Google Cloud项目上启用计费。请查看定价页面了解详细信息。

API参考

工具

| 工具名称 | 描述 | 必需参数 | 可选参数 | |-----------|-------------|---------------------|---------------------| | get_current_air_quality | 获取特定位置的当前空气质量状况 | latitude (float)
longitude (float) | universalAqi (bool)
languageCode (string)
extraComputations (array)
uaqiColorPalette (string) | | get_air_quality_forecast | 获取每小时的空气质量预报 | latitude (float)
longitude (float) | pageSize (int)
pageToken (string)
universalAqi (bool)
languageCode (string)
extraComputations (array) | | get_air_quality_history | 获取历史空气质量数据 | latitude (float)
longitude (float) | hours (int)
pageSize (int)
pageToken (string)
universalAqi (bool)
languageCode (string) | | get_air_quality_heatmap_tile | 获取用于可视化的热图切片图像 | mapType (string)
zoom (int)
x (int)
y (int) | - |

热图的有效地图类型

UAQI_RED_GREEN - 具有红绿调色板的通用空气质量指数
UAQI_INDIGO_PERSIAN - 具有靛蓝 - 波斯调色板的通用空气质量指数
PM25_INDIGO_PERSIAN - PM2.5浓度热图
GBR_DEFRA - 英国DEFRA指数
DEU_UBA - 德国UBA指数
CAN_EC - 加拿大AQHI
FRA_ATMO - 法国ATMO指数
US_AQI - 美国EPA AQI

提示

| 提示名称 | 描述 | 参数 | |-------------|-------------|-----------| | current_air_quality_by_location_prompt | 使用人类可读的位置名称获取当前空气质量（大语言模型将解析为坐标） | location (string) - 例如，"巴黎，法国" | | air_quality_forecast_by_location_prompt | 获取某个位置的空气质量预报 | location (string)
pageSize (int, 可选) | | air_quality_history_by_location_prompt | 获取某个位置的历史空气质量数据 | location (string)
hours (int, 可选) | | air_quality_heatmap_by_location_prompt | 获取某个位置的热图切片 | location (string)
mapType (string)
zoom (int) | | air_quality_heatmap_prompt | 使用直接坐标获取热图切片 | mapType (string)
x (int)
y (int)
zoom (int) |

资源

| 资源URI | 类型 | 描述 | 内容类型 | |--------------|------|-------------|--------------| | example://server-info | 静态 | 基本服务器信息和可用资源 | text/plain |

项目结构

.
├── cmd/
│   └── server/              # 服务器入口点
├── internal/
│   ├── capabilities/        # MCP功能
│   │   ├── prompts/        # 提示定义和处理程序
│   │   ├── resources/      # 资源定义和处理程序
│   │   └── tools/          # 工具实现
│   │       ├── client.go   # Google空气质量API客户端
│   │       ├── types.go    # 共享类型和结构
│   │       ├── current_conditions.go
│   │       ├── forecast.go
│   │       ├── history.go
│   │       └── heatmap.go
│   ├── config/             # 配置管理
│   └── mcp/                # MCP服务器设置
├── .env                    # 环境变量（不在git中）
├── .gitignore
├── go.mod
├── go.sum
└── README.md

开发

构建

go build -o bin/server cmd/server/main.go

运行

./bin/server

测试

go test ./...

配置

环境变量（在.env中设置）：

| 变量 | 描述 | 默认值 | 是否必需 | |----------|-------------|---------|----------| | GOOGLE_AIR_QUALITY_API_KEY | 你的Google空气质量API密钥 | - | ✅ 是 | | MCP_SERVER_NAME | MCP服务器的显示名称 | Google Air Quality MCP Server | 否 | | PORT | HTTP服务器端口 | 8080 | 否 |

故障排除

API密钥问题

错误："API密钥无效"

验证.env文件中的API密钥是否正确
确保在Google Cloud控制台中启用了空气质量API
检查API限制（如果有）是否允许从你的IP发出请求

错误："此API方法需要启用计费"

在你的Google Cloud项目上启用计费
空气质量API可能会产生使用费用

连接问题

错误："地址已在使用中"

另一个进程正在使用端口8080
终止该进程：npx kill-port 8080
或者更改.env文件中的PORT

📄 许可证

本项目采用MIT许可证。

贡献

欢迎贡献代码！请随时提交拉取请求。

资源

支持

如有问题或疑问：

在GitHub上创建一个问题
查看Google空气质量API文档