使用说明

谷歌空气质量MCP服务器

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

特性

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

先决条件

达到1.21或更高
Google Air Quality 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

API密钥设置

步骤1：启用API

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

步骤2：创建API凭据

首选 API和服务 > 凭证
点击 创建凭据 > API密钥
复制生成的API密钥
（推荐）点击 限制密钥 以及：
- 在...之下 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检查员联系

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

api参考

工具

工具名称	描述	必需参数	可选参数
`get_current_air_quality`	获取特定位置的当前空气质量状况	`latitude` （浮动） `longitude` （浮动）	`universalAqi` （布尔） `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

提示

提示名称	描述	参数
`current_air_quality_by_location_prompt`	使用人类可读的位置名称获取当前的空气质量（LLM解析为坐标）	`location` （string）-例如，“法国巴黎”
`air_quality_forecast_by_location_prompt`	获取位置名称的空气质量预报	`location` （字符串） `pageSize` （int，可选）
`air_quality_history_by_location_prompt`	获取位置名称的历史空气质量	`location` （字符串） `hours` （int，可选）
`air_quality_heatmap_by_location_prompt`	获取位置名称的热图块	`location` （字符串） `mapType` （字符串） `zoom` （int）
`air_quality_heatmap_prompt`	使用直接坐标获取热图图块	`mapType` （字符串） `x` （int） `y` （int） `zoom` （int）

资源

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

示例

使用工具

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

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

法学硕士将：

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

使用资源

读取服务器信息：

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):

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

故障排除

API关键问题

错误：“API密钥无效”

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

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

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

连接问题

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

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

许可证

麻省理工学院

贡献

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

资源

支持

对于问题和疑问：

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