Pollen Alert

An MCP (Model Context Protocol) server that provides real-time pollen level alerts and hayfever mitigation tips. It uses the Ambee API to fetch pollen data for any location worldwide, making it available to AI assistants like Claude.

This project is created based on Claude Code Course

Features

Tools

• get_coordinates — Convert a place name into latitude and longitude
• get_pollen_forecast — Get current pollen counts, risk levels, and species-level breakdown for a location

Resources

• pollen://mitigation-guide — Hayfever mitigation strategies
• pollen://allergen-info — Common allergen types and their peak seasons

Prompts

• analyze_pollen_risk — A guided prompt that chains coordinate lookup, pollen forecast, and mitigation advice for a given place

Prerequisites

• Python 3.14+
• uv package manager
• An Ambee API key

Installation

1. Clone the repository:

git clone https://github.com/jaygaha/pollen-alert-mcp.git
cd pollen-alert-mcp

2. Install dependencies with uv:

uv sync

3. Create a .env file in the project root with your Ambee API key:

API_KEY=your_ambee_api_key_here

Usage

Running the server directly

uv run pollen_alert_server

Configuring with Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "pollen-alert": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/pollen-alert-mcp",
        "run",
        "pollen_alert_server"
      ]
    }
  }
}

Configuring with Claude Code (CLI)

1. Add the server:

claude mcp add pollen-alert -- uv --directory /absolute/path/to/pollen-alert-mcp run pollen_alert_server

2. Verify it was registered:

claude mcp list

3. Start a new Claude Code session and ask naturally:

What are the pollen levels in Nerima, Tokyo?

Claude Code will automatically discover and call the get_coordinates and get_pollen_forecast tools.

Note: The MCP server loads when a Claude Code session starts. If you modify the server code, you need to restart your session (/exit then claude) for changes to take effect.

Configuring with Ollama (local models)

You can use this MCP server with locally running models via Ollama using an MCP-compatible client. One option is mcp-cli, which bridges MCP servers to Ollama models.

1. Install an Ollama model with tool-calling support:

ollama pull llama3.1

2. Install mcp-cli:

npx @wong2/mcp-cli

3. Create an MCP configuration file (e.g. mcp.json):

{
  "mcpServers": {
    "pollen-alert": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/pollen-alert-mcp",
        "run",
        "pollen_alert_server"
      ]
    }
  }
}

4. Run mcp-cli with your config:

npx @wong2/mcp-cli --config mcp.json

This connects the pollen alert server to your local Ollama model, allowing it to call the get_coordinates and get_pollen_forecast tools.

Note: Tool-calling quality depends on the model. Models like llama3.1, mistral, and qwen2.5 support tool use. Smaller models may not invoke tools reliably.

Example interactions

Once connected, you can ask your AI assistant things like:

• "What are the pollen levels in Tokyo right now?"
• "Check the pollen forecast for Butwal and tell me if it's safe to go outside."
• "Use the analyze_pollen_risk prompt for Kathmandu."

Project Structure

pollen-alert-mcp/
├── src/
│   ├── __init__.py
│   └── pollen_alert_server/
│       ├── __init__.py              # Entry point
│       ├── server.py                # MCP server implementation
│       └── api_response_model.py    # Pydantic data models
├── pyproject.toml
└── .env                             # API key (not committed)

Architecture Note

This project intentionally uses the low-level Server class from the MCP SDK rather than the higher-level FastMCP wrapper. This makes the MCP protocol mechanics (JSON-RPC, tool registration, resource handling) explicit and easier to understand for beginners learning how MCP servers work.

Future Ideas & Contributions

Here are ideas to improve and extend this project. Contributions are welcome!

Migrate to FastMCP

Refactoring from the low-level Server class to FastMCP would:

• Replace manual list_tools / call_tool dispatching with simple @mcp.tool() decorators
• Replace list_resources / read_resource with @mcp.resource() decorators
• Replace list_prompts / get_prompt with @mcp.prompt() decorators
• Remove boilerplate InitializationOptions setup
• Enable mcp dev server.py for the MCP Inspector (currently unsupported with low-level Server)

Pollen Alert Notifications (n8n Automation)

A detailed architecture plan for automating pollen level notifications using n8n is available in notification-plan.md. It covers scheduled pollen checks, threshold-based alerting, duplicate prevention, and notification delivery via Email, Slack, LINE, and FCM push notifications.

Feature Ideas

• Pollen forecast (multi-day) — Add a tool that returns forecast data for the next 3-7 days, not just current levels
• Allergy severity scoring — Combine pollen counts with user-provided allergy profile (e.g., "allergic to birch and grass") to give a personalized risk score
• Historical comparison — Show how today's pollen levels compare to the same period last year
• Push notifications — Alert users when pollen levels exceed a configured threshold for their saved locations
• Multiple data sources — Integrate additional APIs (e.g., Google Pollen API) for cross-referencing and better accuracy
• Caching layer — Cache API responses (e.g., 15-minute TTL) to reduce Ambee API calls and improve response times
• Rate limiting — Add request throttling to stay within Ambee API limits
• Unit tests — Add test coverage using pytest with mocked API responses
• SSE transport — Add Server-Sent Events transport alongside stdio for web-based MCP clients
• Docker support — Add a Dockerfile for containerized deployment

License

MIT