Google Air Quality MCP

谷歌空气质量MCP服务器

模型上下文协议（MCP）服务器，提供对谷歌API空气质量的访问，使人工智能助手能够检索实时空气质量数据、预测、历史信息和热图可视化。

特性

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

先决条件

• 达到1.21或更高
• Google Air Quality API密钥（请参阅 API密钥设置)

安装

1. 克隆存储库

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

1. 安装依赖项

go mod download

1. 配置环境变量

创建一个 .env 项目根目录中的文件：

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

API密钥设置

步骤1：启用API

1. 转到 谷歌云控制台
2. 创建新项目或选择现有项目
3. 导航至 API和服务 > 图书馆
4. 搜索“空气质量API”
5. 点击 启用

步骤2：创建API凭据

1. 首选 API和服务 > 凭证
2. 点击 创建凭据 > API密钥
3. 复制生成的API密钥
4. （推荐）点击 限制密钥 以及：

- 在...之下 API限制，选择“限制键” - 从下拉列表中选择“空气质量API” - 在...之下 应用程序限制，您可以通过IP、HTTP引用等进行限制。

步骤3：配置服务器

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

GOOGLE_AIR_QUALITY_API_KEY=AIzaSyD...your-key-here

备注：空气质量API可能需要在您的谷歌云项目上启用账单。检查 定价页面 了解详情。

Docker部署

使用Docker

塑造形象：

docker build -t google-air-quality-mcp .

运行容器：

docker run -d \
  -p 8080:8080 \
  -e GOOGLE_AIR_QUALITY_API_KEY=your_api_key_here \
  --name air-quality-mcp \
  google-air-quality-mcp

使用Docker Compose

启动服务：

docker-compose up -d

停止服务：

docker-compose down

查看日志：

docker-compose logs -f

备注：确保你的 .env 文件包含 GOOGLE_AIR_QUALITY_API_KEY 在运行docker compose之前。

图像尺寸

Docker镜像使用Alpine Linux的多阶段构建，生成轻量级镜像（~54MB）：

• 构建阶段：用途 golang:1.24-alpine 编译二进制文件
• 最后阶段：用途 alpine:latest 仅使用已编译的二进制和CA证书
• 安全：以非root用户身份运行，以增强安全性

用法

运行服务器

go run cmd/server/main.go

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

与MCP检查员联系

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

api参考

工具

languageCode （字符串） extraComputations （数组） uaqiColorPalette （字符串）| | get_air_quality_forecast |获取每小时的空气质量预报| latitude （浮动） longitude （浮动）| pageSize （int） pageToken （字符串） universalAqi （布尔） languageCode （字符串） extraComputations （数组）| | get_air_quality_history |获取历史空气质量数据| latitude （浮动） longitude （浮动）| hours （int） pageSize （int） pageToken （字符串） universalAqi （布尔） languageCode （字符串）| | get_air_quality_heatmap_tile |获取热图块图像以进行可视化| mapType （字符串） zoom （int） x （int） y （int）|-|

热图的有效地图类型

• UAQI_RED_GREEN -通用AQI，红绿色调色板
• UAQI_INDIGO_PERSIAN -带有靛波斯色调的通用AQI
• PM25_INDIGO_PERSIAN -PM2.5浓度热图
• GBR_DEFRA -英国DEFRA指数
• DEU_UBA -德国UBA指数
• CAN_EC -加拿大AQHI
• FRA_ATMO -法国ATMO指数
• US_AQI -美国环保署AQI

提示

mapType （字符串） zoom （int）| | air_quality_heatmap_prompt |使用直接坐标获取热图图块| mapType （字符串） x （int） y （int） zoom （int）|

资源

示例

使用工具

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

{
  "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
  }
}

使用提示

提示允许您使用自然语言位置名称。LLM将自动将它们解析为坐标。

提示用法示例：

Use the current_air_quality_by_location_prompt with location "Tokyo, Japan"

法学硕士将：

1. 将“日本东京”定为坐标（35.6762139.6503）
2. 打电话给 get_current_air_quality 具有这些坐标的工具
3. 返回空气质量数据

使用资源

读取服务器信息：

URI: example://server-info

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

项目结构

.
├── cmd/
│   └── server/              # Server entry point
├── internal/
│   ├── capabilities/        # MCP capabilities
│   │   ├── prompts/        # Prompt definitions and handlers
│   │   ├── resources/      # Resource definitions and handlers
│   │   └── tools/          # Tool implementations
│   │       ├── client.go   # Google Air Quality API client
│   │       ├── types.go    # Shared types and structures
│   │       ├── current_conditions.go
│   │       ├── forecast.go
│   │       ├── history.go
│   │       └── heatmap.go
│   ├── config/             # Configuration management
│   └── mcp/                # MCP server setup
├── .env                    # Environment variables (not in git)
├── .gitignore
├── go.mod
├── go.sum
└── README.md

发展

建筑

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

跑步

./bin/server

测试

go test ./...

配置

环境变量（设置于 .env):

故障排除

API关键问题

错误：“API密钥无效”

• 在中验证您的API密钥是否正确 .env
• 确保在Google云控制台中启用空气质量API
• 检查API限制（如果有）是否允许来自IP的请求

错误：“此API方法要求启用计费”

• 在您的Google Cloud项目上启用计费
• 空气质量API可能有使用成本

连接问题

错误：“地址已在使用中”

• 另一个进程正在使用端口8080
• 终止进程： npx kill-port 8080
• 或更改 PORT 在 .env

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

资源

• 模型上下文协议文档
• Google空气质量API文档
• MCP Go SDK
• MCP检查员

支持

对于问题和疑问：

• 打开一个问题
• 检查 Google空气质量API文档