Eris ☁️ — Public Weather API & MCP Server

A battle-tested, open-source weather API and public MCP server - free to use, free to fork, maintained since 2017.

Live API: https://weather-api.madadipouya.com
Swagger Docs: https://weather-api.madadipouya.com/swagger-ui/index.html
MCP Endpoint: https://weather-api.madadipouya.com/mcp

What is Eris?

Eris is a Spring Boot weather service that consolidates OpenWeatherMap, OpenStreetMap, and IP geolocation into a single clean API. It exposes weather data by coordinates or IP address, and since 2026, also serves as a public MCP (Model Context Protocol) server that any AI agent can plug into directly.

It's simple by design. But it's built on a foundation that doesn't cut corners.

🤖 MCP (Use Eris as an AI Tool)

Eris exposes a public MCP server endpoint that works out of the box with any MCP compatible AI agent (Claude, Cursor, and others).

MCP Server URL:

https://weather-api.madadipouya.com/mcp

Connect to Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "eris-weather": {
      "type": "sse",
      "url": "https://weather-api.madadipouya.com/mcp"
    }
  }
}

Available MCP Tools

Tool	Description
`get_current_weather_by_latitude_and_longitude`	Get weather for a specific location by coordinates
`get_current_weather_by_ip_address`	Get weather based on caller's IP address

No API key required. No sign-up. Just point and use.

For testing MCP locally with tools like mcp-cli, see mcp/README.md.

✨ Why Eris?

This project has been quietly doing things right for nearly a decade. Here's what's under the hood:

Area	Detail
Test Coverage	100% — enforced via SonarCloud on every build
Code Quality	Zero code smells, zero duplications. SonarCloud Quality Gate always green
CI/CD Pipeline	Auto builds, auto releases to GitHub Releases, auto pushes Docker image to Docker Hub
Auto-deployment	Merges to `master` trigger live deployment via Adnanh Webhook + Docker Swarm
Security Scanning	NVD dependency vulnerability check runs on every merge to `develop`
Versioned Releases	Automatic release notes and GitHub Release artifacts on every tag
MCP Ready	Public MCP server endpoint, usable by any AI agent without setup
Swagger Docs	Full interactive API documentation at `/swagger-ui/index.html`
Clustering	Docker Swarm support with provided `docker-compose-swarm.yml`
Heroku	One click deployment button
Longevity	Maintained from Spring Boot 1 → 3.5 over 8 years

🚀 Quick Start

The fastest way to get weather data, no account needed:

# By coordinates
$ curl "https://weather-api.madadipouya.com/v1/weather/current?lat=51.5074&lon=-0.1278"

# By IP address (uses caller's IP)
$ curl "https://weather-api.madadipouya.com/v1/weather/currentbyip"

Full API reference with live examples: Swagger UI →

API Endpoints

Endpoint	Parameters	Description
`GET /v1/weather/current`	`lat`, `lon`, `fahrenheit` (optional)	Weather by coordinates
`GET /v1/weather/currentbyip`	`fahrenheit` (optional)	Weather by caller IP

For full request/response examples, see the GitHub Pages documentation.

🐳 Run Your Own Instance

Docker (recommended)

$ docker run -p 8080:8080 \
  -e OPENWEATHERMAP_API_KEY=your-api-key \
  -e ACTUATOR_USERNAME=your-username \
  -e ACTUATOR_PASSWORD=your-password \
  kasramp/eris:latest

Images are automatically built and pushed to Docker Hub on every release.

Docker Swarm (cluster mode)

$ export OPENWEATHERMAP_API_KEY=your-api-key
$ export ACTUATOR_USERNAME=your-username
$ export ACTUATOR_PASSWORD=your-password
$ docker stack deploy --with-registry-auth -c docker-compose-swarm.yml eris_stack

Heroku (one-click)

Local Development

Requires JDK 25 and Maven.

$ git clone https://github.com/kasramp/Eris.git
$ cd Eris
$ mvn spring-boot:run

Build Über-JAR

$ mvn clean install
$ cd target
$ java -jar eris-*.jar

🔧 CI/CD & Engineering Highlights

Pull Request → develop
    └── SonarCloud analysis (quality gate + 100% coverage check)
    └── NVD dependency vulnerability scan

Merge to master
    └── GitHub Actions build
    └── Docker image pushed to Docker Hub  →  kasramp/eris:latest
    └── GitHub Release created with auto-generated release notes
    └── Adnanh Webhook triggers live redeployment on weather-api.madadipouya.com

The live instance runs in Docker Swarm with multiple replicas for availability.

Tech Stack

Java 25 / Spring Boot 3.5
Maven
Docker / Docker Swarm
SonarCloud (quality + coverage)
GitHub Actions (CI/CD)
Spring MCP (MCP server)
Springdoc / Swagger UI (API docs)

Data sources: OpenWeatherMap · OpenStreetMap · IP-API

Contributing

All contributions are welcome including bug reports, pull requests, and ideas. Please open an issue first for significant changes.

License

Eris is free software licensed under the GNU General Public License v3.