schlpbch/aareguru-mcp

Aareguru MCP Server

MCP server for Swiss Aare river data, enabling AI assistants like Claude to answer questions about swimming conditions, water temperature, flow rates, and safety.

🚀 Quick Start

Use directly from FastMCP Cloud (no installation needed):

Add it is as custom connector in Claude Desktop:

No authentication is needed.

Altnernatively, you can add the file via option in Claude -> Settings -> Extensions. Or edit the Claude desktop config file directly:

{
  "mcpServers": {
    "aareguru": {
      "url": "https://aareguru.fastmcp.app/mcp"
    }
  }
}

📸 Screenshots

🎯 Features

🛠️ Tools

BAFU Safety Thresholds

📊 Resources

💬 Prompts

💻 Local Installation

# Install uv and clone
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/schlpbch/aareguru-mcp.git && cd aareguru-mcp
uv sync

# Run tests
uv run pytest

Claude Desktop (Local)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aareguru": {
      "command": "uv",
      "args": ["--directory", "/path/to/aareguru-mcp", "run", "aareguru-mcp"]
    }
  }
}

🐳 Docker

cp .env.example .env
docker-compose up -d
curl http://localhost:8000/health

☁️ Hosting

FastMCP Cloud (Recommended)

This server is deployed on FastMCP Cloud, a managed platform for MCP servers with zero-config deployment.

Features:

• ✅ Zero-Config Deployment - Connect GitHub repo, automatic deployment
• ✅ Serverless Scaling - Scale from 0 to millions of requests instantly
• ✅ Git-Native CI/CD - Auto-deploy on push to main, branch deployments for PRs
• ✅ Built-in Security - OAuth support, token management, secure endpoints
• ✅ MCP Analytics - Request/response tracking, tool usage insights
• ✅ Free Tier - Available for personal servers

Deployment Steps:

1. Sign in to fastmcp.cloud with GitHub
2. Create Project and link your repository
3. Deploy - Platform automatically clones, builds, and deploys
4. Access - Get your unique URL (e.g., https://aareguru.fastmcp.app/mcp)

Configuration:

No special configuration needed! FastMCP Cloud auto-detects FastMCP servers. The server runs with:

• Health endpoint: https://your-app.fastmcp.app/health
• MCP endpoint: https://your-app.fastmcp.app/mcp

Pricing:

• Free tier for personal projects
• Pay-as-you-go for teams (usage-based)

Alternative Hosting Options

FastMCP servers can be deployed to any Python-compatible cloud platform:

Container Platforms:

• Google Cloud Run
• AWS ECS/Fargate
• Azure Container Instances

PaaS Providers:

• Railway
• Render
• Vercel

Cloud VMs:

• AWS EC2
• Google Compute Engine
• Azure VMs

Deployment Pattern:

# For HTTP deployment, modify server to use HTTP transport
from fastmcp import FastMCP

mcp = FastMCP("aareguru")
# ... register tools ...

if __name__ == "__main__":
    mcp.run(transport="sse")  # Server-Sent Events for HTTP

Then containerize with Docker and deploy to your chosen platform.

📊 Monitoring & Observability

Prometheus Metrics

The server exposes Prometheus-compatible metrics at /metrics for monitoring:

Available Metrics:

• aareguru_mcp_tool_calls_total - Counter of tool invocations by name and status
• aareguru_mcp_tool_duration_seconds - Histogram of tool execution times
• aareguru_mcp_api_requests_total - Counter of Aareguru API requests
• aareguru_mcp_errors_total - Counter of errors by type and component
• aareguru_mcp_active_requests - Gauge of currently active requests

Example:

curl http://localhost:8000/metrics

Rate Limiting

HTTP endpoints are protected with rate limiting:

• Default limits: 100 requests/minute, 1000 requests/hour
• Health endpoint: 60 requests/minute
• Headers: Rate limit info included in responses
• 429 responses: Automatic retry-after headers when limits exceeded

🧪 Development

uv run pytest                    # Run tests
uv run pytest --cov=aareguru_mcp # With coverage
uv run black src/ tests/         # Format
uv run ruff check src/ tests/    # Lint

📁 Project Structure

aareguru-mcp/
├── src/aareguru_mcp/     # Server, client, models, config
├── tests/                # 200 tests, 87% coverage
├── docs/                 # API docs, testing, implementation
├── mcp_server.py         # FastMCP CLI entry
└── pyproject.toml

🔒 Data Attribution

Data from BAFU, Aare.guru, MeteoSchweiz, Meteotest.

Non-commercial use only - Contact: aaregurus@existenz.ch

📄 License

MIT License - See

Built with ❤️ for the Swiss Aare swimming community