Google Air Quality MCP Server

A Model Context Protocol (MCP) server that provides access to Google's Air Quality API, enabling AI assistants to retrieve real-time air quality data, forecasts, historical information, and heatmap visualizations.

Features

• 🌍 Real-time Air Quality Data - Current conditions for any location worldwide
• 📊 Forecasts - Hourly air quality predictions
• 📈 Historical Data - Access past air quality measurements
• 🗺️ Heatmap Visualizations - Generate air quality heatmap tiles
• 🤖 LLM-Friendly Prompts - Natural language location queries
• 📦 MCP Resources - Structured data access via URI templates

Prerequisites

• Go 1.21 or higher
• Google Air Quality API key (see API Key Setup)

Installation

1. Clone the repository

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

2. Install dependencies

go mod download

3. Configure environment variables

Create a .env file in the project root:

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

API Key Setup

Step 1: Enable the API

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services > Library
4. Search for "Air Quality API"
5. Click Enable

Step 2: Create API Credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > API Key
3. Copy the generated API key
4. (Recommended) Click Restrict Key and:
   • Under API restrictions, select "Restrict key"
   • Choose "Air Quality API" from the dropdown
   • Under Application restrictions, you can restrict by IP, HTTP referrer, etc.

Step 3: Configure the Server

Add your API key to the .env file:

GOOGLE_AIR_QUALITY_API_KEY=AIzaSyD...your-key-here

Note: The Air Quality API may require billing to be enabled on your Google Cloud project. Check the pricing page for details.

Docker Deployment

Using Docker

Build the image:

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

Run the container:

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

Using Docker Compose

Start the service:

docker-compose up -d

Stop the service:

docker-compose down

View logs:

docker-compose logs -f

Note: Make sure your .env file contains GOOGLE_AIR_QUALITY_API_KEY before running docker-compose.

Image Size

The Docker image uses a multi-stage build with Alpine Linux, resulting in a lightweight image (~54MB):

• Build stage: Uses golang:1.24-alpine to compile the binary
• Final stage: Uses alpine:latest with only the compiled binary and CA certificates
• Security: Runs as non-root user for enhanced security

Usage

Running the Server

go run cmd/server/main.go

The server will start on http://localhost:8080 with the MCP endpoint at /mcp.

Connecting with MCP Inspector

1. Open MCP Inspector
2. Connect to http://localhost:8080/mcp
3. Explore available tools, prompts, and resources

API Reference

Tools

Valid Map Types for Heatmap

• UAQI_RED_GREEN - Universal AQI with red-green color palette
• UAQI_INDIGO_PERSIAN - Universal AQI with indigo-persian palette
• PM25_INDIGO_PERSIAN - PM2.5 concentration heatmap
• GBR_DEFRA - UK DEFRA index
• DEU_UBA - German UBA index
• CAN_EC - Canadian AQHI
• FRA_ATMO - French ATMO index
• US_AQI - US EPA AQI

Prompts

Resources

Examples

Using Tools

Get current air quality for San Francisco:

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

Get 24-hour forecast for New York:

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

Get historical data for London:

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

Using Prompts

Prompts allow you to use natural language location names. The LLM will automatically resolve them to coordinates.

Example prompt usage:

Use the current_air_quality_by_location_prompt with location "Tokyo, Japan"

The LLM will:

1. Resolve "Tokyo, Japan" to coordinates (35.6762, 139.6503)
2. Call the get_current_air_quality tool with those coordinates
3. Return the air quality data

Using Resources

Read server information:

URI: example://server-info

This returns basic information about the server and available resources.

Project Structure

.
├── 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

Development

Building

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

Running

./bin/server

Testing

go test ./...

Configuration

Environment variables (set in .env):

Troubleshooting

API Key Issues

Error: "API key not valid"

• Verify your API key is correct in .env
• Ensure the Air Quality API is enabled in Google Cloud Console
• Check that API restrictions (if any) allow requests from your IP

Error: "This API method requires billing to be enabled"

• Enable billing on your Google Cloud project
• The Air Quality API may have usage costs

Connection Issues

Error: "address already in use"

• Another process is using port 8080
• Kill the process: npx kill-port 8080
• Or change the PORT in .env

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Resources

• Model Context Protocol Documentation
• Google Air Quality API Documentation
• MCP Go SDK
• MCP Inspector

Support

For issues and questions:

• Open an issue on GitHub
• Check the Google Air Quality API documentation