Skip to main content
Glama
jaygaha

pollen-alert-mcp

by jaygaha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Pollen Alert MCP Server

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

Related MCP server: Weather MCP Server

Prerequisites

Installation

  1. Clone the repository:

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

  1. Install dependencies with uv:

uv sync

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

  1. Verify it was registered:

claude mcp list

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

  1. Install mcp-cli:

npx @wong2/mcp-cli

  1. 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"
      ]
    }
  }
}

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

Available Tools

2 tools
get_coordinatesA

Convert a place name into latitude and longitude.

ParametersJSON Schema
NameRequiredDescriptionDefault
placeYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It only states the basic conversion but omits details like output format, accuracy, rate limits, or potential failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is front-loaded and contains no unnecessary words, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one string input, no output schema), the description is complete enough for an agent to understand its basic function, though details about the output format are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description adds meaning by specifying that 'place' is a place name, compensating for the lack of schema-level documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Convert' and resource 'place name' to clearly state the tool's function, and it differs from the sibling tool 'get_pollen_forecast' which focuses on pollen data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or avoid this tool versus alternatives is provided, but the purpose is simple and distinct from the only sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pollen_forecastB

Get pollen levels (tree, grass, weed) and species-level risk for a specific latitude and longitude.

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes
longitudeYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It does not disclose data freshness, global coverage, units, accuracy, or rate limits. Only basic purpose is stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff. Efficiently communicates the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and 2 parameters, the description gives a basic idea of output components (tree, grass, weed, species risk) but lacks details on format, units, or completeness. Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and description only repeats parameter names without adding constraints (e.g., valid ranges). It does not explain expected formats or any units for the output parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves pollen levels for tree, grass, and weed, including species-level risk for a given latitude/longitude. It is distinct from the sibling tool 'get_coordinates' which likely converts addresses to coordinates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, when not to use it, or any prerequisites such as coordinate validation. The sibling 'get_coordinates' might be needed first, but this is not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_coordinates
    • First observedget_pollen_forecast
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

Each tool has a distinct purpose: one converts place names to coordinates, the other retrieves pollen forecasts using coordinates. There is no overlap or ambiguity.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern with snake_case (get_coordinates, get_pollen_forecast), making them predictable and easy to understand.

Tool Count4/5

With only two tools, the server feels slightly thin, but it covers the essential workflow for a pollen alert service: location lookup and forecast retrieval. The count is reasonable for a focused domain.

Completeness4/5

The server provides the core functionality needed to get pollen alerts by location. A minor gap is the lack of a direct place-name-to-forecast tool, but the separate steps are logically sound.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers