# 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](https://www.getambee.com/) 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](https://docs.astral.sh/uv/) package manager
- An [Ambee API](https://www.getambee.com/) key

## Installation

1. Clone the repository:

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

2. Install dependencies with uv:

```bash
uv sync
```

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

```bash
API_KEY=your_ambee_api_key_here
```

## Usage

### Running the server directly

```bash
uv run pollen_alert_server
```

### Configuring with Claude Desktop

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

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

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

2. Verify it was registered:

```bash
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](https://ollama.com/) using an MCP-compatible client. One option is [mcp-cli](https://github.com/wong2/mcp-cli), which bridges MCP servers to Ollama models.

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

```bash
ollama pull llama3.1
```

2. Install mcp-cli:

```bash
npx @wong2/mcp-cli
```

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

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

```bash
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`](https://github.com/modelcontextprotocol/python-sdk#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`](./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