Content
# Weather MCP Server
## Overview
This project implements a Model Context Protocol (MCP) server that provides weather information services. It leverages the National Weather Service (NWS) API to fetch weather alerts and forecasts, and exposes them as tools that can be used by MCP clients like Claude.
The server is built with a modular architecture following best practices for Python projects, making it easy to maintain and extend.
### Features
- **Weather Tools**: Get weather alerts for states and forecasts for specific coordinates
- **System Tools**: Run shell commands and view system process information
- **MCP Integration**: Seamlessly integrates with MCP clients like Claude Desktop
## Installation
### Prerequisites
- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager
### Setup
1. Clone the repository:
```bash
git clone https://github.com/yourusername/weather.git
cd weather
```
2. Install dependencies using uv:
```bash
make install
```
3. For development, install additional dependencies:
```bash
make dev
```
## Usage
### Running the Server
To start the MCP server:
```bash
make run
```
Or directly with uv:
```bash
uv run python -m main
```
### Connecting to Claude Desktop
1. Update your Claude Desktop configuration to include the weather server:
```json
{
"mcpServers": {
"weather": {
"command": "python",
"args": ["-m", "main"],
"cwd": "/path/to/weather"
}
}
}
```
2. Restart Claude Desktop to apply the changes
3. In Claude Desktop, you can now select the "weather" MCP server from the MCP server dropdown menu
The weather MCP server will be available to Claude Desktop, allowing you to interact with weather data directly in your conversations.
### Example Queries
Once connected, you can ask Claude:
- "What are the current weather alerts in CA?"
- "What's the forecast for latitude 37.7749, longitude -122.4194?"
- "What processes are using the most CPU on my system?"
## Project Structure
```
weather/
├── src/
│ └── weather/
│ ├── __init__.py # Package initialization
│ ├── server.py # Main server setup
│ ├── tools/ # Tool implementations
│ │ ├── __init__.py
│ │ ├── weather_tools.py
│ │ └── system_tools.py
│ ├── resources/ # Resource implementations
│ │ ├── __init__.py
│ │ └── system_resources.py
│ ├── services/ # External service integrations
│ │ ├── __init__.py
│ │ ├── weather_service.py
│ │ └── system_service.py
│ └── utils/ # Helper functions
│ ├── __init__.py
│ ├── http.py
│ └── formatting.py
├── tests/ # Test suite
├── main.py # Entry point
├── pyproject.toml # Dependencies and metadata
├── Makefile # Build commands
└── README.md # This file
```
## Make Targets
The project includes several make targets to simplify development:
| Target | Description |
|--------------|----------------------------------------------|
| `install` | Install project dependencies using uv |
| `lint` | Run ruff linter with auto-fix using uv |
| `format` | Run black formatter using uv |
| `format-check` | Check if files would be reformatted by black |
| `lint-format`| Run both linter and formatter |
| `test` | Run tests using pytest with uv |
| `clean` | Remove build artifacts and cache files |
| `outdated` | Check for outdated dependencies using uv |
| `upgrade-deps` | Upgrade all outdated dependencies using uv |
| `run` | Start the MCP server using uv |
| `inspector` | Start the MCP Inspector for testing |
| `hooks` | Install git hooks |
| `dev-server` | Start the MCP server in development mode |
| `stop-server`| Stop the MCP server and Inspector |
| `claude-install` | Install the server in Claude Desktop |
| `claude-uninstall` | Uninstall the server from Claude Desktop |
Run `make help` to see all available targets.
### Using with Claude Desktop
To use the weather MCP server with Claude Desktop:
1. Install the server in Claude Desktop:
```bash
make claude-install
```
This will:
- Use the MCP CLI to install the server in Claude Desktop
- Install the project in editable mode (`-e .`)
- Register the server with the name "weather"
- Configure the server to run from your project directory
2. Restart Claude Desktop to apply the changes
3. In Claude Desktop, you can now select the "weather" MCP server from the MCP server dropdown menu
The weather MCP server will be available to Claude Desktop, allowing you to interact with weather data directly in your conversations.
To uninstall the server from Claude Desktop:
```bash
make claude-uninstall
```
This will remove the weather MCP server configuration from Claude Desktop. You'll need to restart Claude to apply the changes.
### Development Mode
For active development with automatic reloading when code changes:
```bash
# Start the server in development mode with the MCP Inspector
make dev-server
```
This will:
1. Start the MCP server using the `mcp dev` command
2. Install the project in editable mode (`-e .`)
3. Launch the MCP Inspector automatically
4. Enable automatic reloading when your code changes
The MCP Inspector will be available at http://localhost:5173 in your web browser.
To stop the server and Inspector:
```bash
make stop-server
```
This setup is ideal for iterative development as the server will automatically reload when you make changes to your code.
### Inspector Features
The MCP Inspector allows you to:
1. **Explore Tools**: View all available tools, their parameters, and documentation.
2. **Call Tools**: Execute tools with custom parameters and see the results.
3. **Browse Resources**: View all available resources and their current values.
4. **Test Prompts**: If your server provides prompt templates, you can test them with different inputs.
5. **View Logs**: See detailed logs of all interactions between the Inspector and your server.
### Testing Weather Tools
With the Inspector, you can easily test the weather tools:
1. Find the `get_weather_alerts` tool in the Inspector interface
2. Enter a state code (e.g., "CA", "NY", "FL") in the parameters field
3. Execute the tool and view the results
Similarly, you can test the `get_forecast` tool by providing latitude and longitude coordinates.
### Testing System Tools
The Inspector also makes it easy to test system tools:
1. Find the `run_shell_command` tool
2. Enter a safe command (e.g., "ls -la", "echo hello") in the parameters field
3. Execute the tool and view the results
### Debugging with the Inspector
The Inspector is particularly useful for debugging:
1. It shows detailed error messages if a tool call fails
2. You can see the exact request and response payloads
3. It helps identify issues with parameter validation or tool implementation
For more information about the MCP Inspector, visit the [Model Context Protocol documentation](https://modelcontextprotocol.io/).
## Testing Locally
You can test your MCP server locally using the MCP CLI tool that comes with the `mcp[cli]` package:
1. Start your server:
```bash
make run
```
2. In a separate terminal, use the MCP CLI to interact with your server:
```bash
# List all available tools
make inspector
# Call a specific weather tool
mcp call-tool http://localhost:8000 get_weather_alerts --args '{"state": "CA"}'
# Get a weather forecast
mcp call-tool http://localhost:8000 get_forecast --args '{"latitude": 37.7749, "longitude": -122.4194}'
# List system resources
mcp list-resources http://localhost:8000
# Get system processes
mcp get-resource http://localhost:8000 top_processes
```
If you're using uv directly, you can run the MCP CLI with:
```bash
uv run mcp list-tools http://localhost:8000
```
## Development
### Adding New Tools
To add a new tool to the server:
1. Create a function in the appropriate tools module
2. Register it with the `@server.tool()` decorator
3. Update the tool registration in `tools/__init__.py`
Example:
```python
@server.tool()
async def my_new_tool(param1: str, param2: int) -> str:
"""
Tool description.
Args:
param1: Description of param1
param2: Description of param2
Returns:
Description of return value
"""
# Implementation
return result
```
### Adding New Resources
To add a new resource:
1. Create a function in the appropriate resources module
2. Register it with the `@server.resource()` decorator
3. Update the resource registration in `resources/__init__.py`
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [National Weather Service API](https://www.weather.gov/documentation/services-web-api) for weather data
