Google Air Quality MCP

🚀 Google Air Quality MCP Server

This Model Context Protocol (MCP) server offers access to Google's Air Quality API, allowing AI assistants to obtain real - time air quality data, forecasts, historical information, and heatmap visualizations.

🚀 Quick Start

The Google Air Quality MCP Server enables seamless access to Google's Air Quality API. Follow the steps below to get started:

1. Ensure you have Go 1.21 or higher installed and obtain a Google Air Quality API key.
2. Clone the repository, install dependencies, and configure environment variables.
3. Run the server and start exploring air quality data.

✨ Features

• 🌍 Real - time Air Quality Data: Get current air quality 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: Use natural language for location queries.
• 📦 MCP Resources: Access structured data via URI templates.

📦 Installation

Prerequisites

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

Steps

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

📚 Documentation

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

⚠️ Important Note

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

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

💻 Usage Examples

Basic Usage

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

This code gets the current air quality for San Francisco.

Advanced Usage

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

This code gets a 24 - hour air quality forecast for New York.

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

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

This project is licensed under the MIT license.

🔗 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.