AccuWeather MCP

MCP server providing weather tools with data sourced from AccuWeather.
Open source Open in the app JSON README (API)
About

MCP server providing weather tools with data sourced from AccuWeather.
Details

Kind: MCP servers
Topic: Maps, weather & travel
Publisher: jonjam
Origin: official
Category: ferramentas
Transport: local
Version: 1.4.11
Last push: 2026-06-11T07:20:37Z
Repository state: ativo
Language: Java
License: MIT
Added: 2026-08-29 03:01:59
Updated: 2026-08-29 03:01:59
Origin id: io.github.JonJam/accuweather-mcp
README


# accuweather-mcp

- [Setup](#setup)
- [Run](#run)
- [Testing](#testing)
  - [Unit and integration testing](#unit-and-integration-testing)
  - [Mutation testing](#mutation-testing)
  - [MCP Inspector](#mcp-inspector)
  - [AI chat (Claude, Cursor)](#ai-chat-claude-cursor)
  - [Docker](#docker)
- [Patterns and practices](#patterns-and-practies)
  - [Git](#git)
  - [Spotless](#spotless)
  - [Checkstyle](#checkstyle)
  - [MCP](#mcp)
- [MCP Registry](#mcp-registry)
- [Future improvements](#future-improvements)


## Setup

- Define the following environment variables in your system
```
export ACCUWEATHER_API_KEY=replace-with-your-api-key
```

- Define a `application-local.yaml` in `src/main/resources/application.yaml` with the following content:

```YAML
logging:
  console:
    enabled: true
```

- If using Cursor, add the following documentation sources:
  - [Spring AI documentation](https://docs.spring.io/spring-ai/reference/)
  - [Wiremock documentation][[https://wiremock.org/docs/]](https://wiremock.org/docs/]) 
  - [Lombok documentation][[https://projectlombok.org/features/]](https://projectlombok.org/features/]) 
  - [PIT documentation](https://pitest.org/)
  - [gradle-pitest-plugin documentation](https://gradle-pitest-plugin.solidsoft.info/)

## Run

- Run with `SPRING_PROFILES_ACTIVE=local ./gradlew bootRun`

## Testing
**Note**: If you enable the Java debugger, it will produce output to standard out which will trigger errors in the stdio MCP protocol.

### Unit and integration testing
Unit and integration tests use [mockito](https://site.mockito.org/) and [wiremock](https://wiremock.org/). To run the tests, use:

```bash
./gradlew build
```

### Mutation testing
This project uses [PIT](https://pitest.org/) mutation testing via the [gradle-pitest-plugin](https://gradle-pitest-plugin.solidsoft.info/) to verify that tests detect injected faults, complementing JaCoCo line coverage.

- `./gradlew pitest` — run mutation tests over `com.jonjam.accuweathermcp.*` (excluding DTOs and the bootstrap class).
- Open `build/reports/pitest/index.html` to review results. Surviving mutants indicate code that is executed by tests but where a fault would not be caught.


### MCP Inspector

To test with [MCP Inspector]([https://modelcontextprotocol.io/docs/tools/inspector](https://modelcontextprotocol.io/docs/tools/inspector)), run the following from the root of the repo:

```bash
npx @modelcontextprotocol/inspector -e 'JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005' java -jar "build/libs/accuweather-mcp-local-snapshot.jar"
```

This was sourced from this [blog.](https://medium.com/@tsteidle/creating-an-mcp-server-with-spring-boot-setup-debugging-and-unit-testing-8edbac9da5a6)

### AI chat (Claude, Cursor)

1. Add this configuration to the MCP settings:

```json
{
  "mcpServers": {
    "accuweather-mcp": {
      "command": "PATH_TO_JAVA",
      "args": ["-jar", "ABSOLUTE_PATH_TO_REPO/build/libs/accuweather-mcp-local-snapshot.jar"],
      "env": {
        "ACCUWEATHER_API_KEY": "API_KEY"
      }
    }
  }
}
```

If you are using SDKMAN, `command` should be `~/.sdkman/candidates/java/current/bin/java`

This was sourced from the [MCP docs](https://modelcontextprotocol.io/docs/develop/build-server#testing-your-server-with-claude-for-desktop-3).

Example user prompt:

```
Use the accuweather-mcp to look up the current weather in Manchester, UK.
```

### Docker

This project uses the [Jib Gradle plugin](https://github.com/GoogleContainerTools/jib) to build a Docker image.

- Build and load the image into your local Docker daemon:

```bash
./gradlew jibDockerBuild
```

The default image name is `jonjam/accuweather-mcp`.

To use the docker image with MCP Inspector, the command looks as follows:

```bash
npx @modelcontextprotocol/inspector docker run --rm -i --env "ACCUWEATHER_API_KEY=$ACCUWEATHER_API_KEY" jonjam/accuweather-mcp:latest
```

## Patterns and practies
More information about patterns and practises for this project can be found in AGENTS.md.

### Git

This project uses [semantic-release](https://semantic-release.gitbook.io/semantic-release) to automate versioning, changelog generation, and publishing. 

**Important:** Commit messages that are intended to trigger a release must be prefixed according to the [Conventional Commits](https://semantic-release.gitbook.io/semantic-release#commit-message-format) standard. For example:

- `feat: add new forecast endpoint`
- `fix: correct hourly forecast time calculation`

### Spotless

This project uses the Spotless Gradle plugin to enforce a consistent Java style.

- `./gradlew spotlessApply` — format sources and fix style issues.
- `./gradlew spotlessCheck` — verify formatting without changing files.

### Checkstyle

Static analysis and broader code-quality checks are handled by Checkstyle using a Google-style-based configuration (with formatting delegated to Spotless):

- `./gradlew checkstyleMain` — run Checkstyle over main sources.
- `./gradlew checkstyleTest` — run Checkstyle over test sources.

### MCP
- **Tools** Ensure to handle errors (i.e. validation) according to the [specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling)

## MCP Registry

This server is published to the [MCP Registry](https://modelcontextprotocol.io/registry). 

When using an MCP client that supports the registry (e.g. Cursor, Claude Desktop), you can add `io.github.jonjam/accuweather-mcp` from the registry and configure your AccuWeather API key as the `ACCUWEATHER_API_KEY` environment variable.

## Future improvements
- Improve error handling in gateway classes based upon [AccuWeather status codes](https://developer.accuweather.com/documentation/http-status-codes)
- Add in-memory caching for AccuWeather API calls that caches data according to [expires header](https://developer.accuweather.com/documentation/best-practices#use-the-expires-header)
- Add ability to specify desired metric (i.e. Celsius or Fahrenheit) in Tools
- End to end integration tests based on [Spring AI Examples](https://github.com/spring-projects/spring-ai-examples/tree/main/integration-testing)