Build-your-first-MCP-Server by bhaveshxop - MCP Server

Weather MCP Server 🌤️

A beginner-friendly Model Context Protocol (MCP) server that provides real-time weather data to Claude Desktop. This project serves as a perfect starting point for anyone learning to build MCP servers.

🚀 What is MCP?

The Model Context Protocol (MCP) allows AI assistants like Claude to securely connect to external data sources and tools. This weather server demonstrates how to:

Create a basic MCP server using Python
Integrate with Claude Desktop
Fetch real-time data from external APIs
Handle errors gracefully

✨ Features

🌪️ Weather Alerts: Get active weather alerts for any US state
📊 Weather Forecasts: Get detailed 5-day forecasts for any location
🔧 No External Dependencies: Uses only Python standard library (urllib)
📝 Comprehensive Logging: Built-in error handling and debugging
🚀 Easy Setup: Works out of the box with minimal configuration

📦 Installation

Prerequisites

Python 3.8+ installed on your system
Claude Desktop application
Internet connection for weather data

Step 1: Clone the Repository

git clone https://github.com/your-username/weather-mcp-server.git
cd weather-mcp-server

Step 2: Install MCP Dependencies

pip install mcp

Note: This is the only dependency required! The weather server uses Python's built-in urllib library for HTTP requests to keep things simple.

Step 3: Test the Server

python weather.py

You should see: Starting Simple Weather MCP Server...

The server will run and wait for connections (this is normal behavior).

🔧 Claude Desktop Integration

Step 1: Find Your Claude Desktop Config

The configuration file is located at:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Update Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/your/weather-mcp-server/weather.py"]
    }
  }
}

Windows Example:

{
  "mcpServers": {
    "weather": {
      "command": "C:\\Python312\\python.exe",
      "args": ["C:\\Users\\YourName\\weather-mcp-server\\weather.py"]
    }
  }
}

macOS/Linux Example:

{
  "mcpServers": {
    "weather": {
      "command": "/usr/bin/python3",
      "args": ["/Users/YourName/weather-mcp-server/weather.py"]
    }
  }
}

Step 3: Restart Claude Desktop

Completely close Claude Desktop
Reopen Claude Desktop
Look for the weather server connection status

🧪 Testing the Integration

Once connected, try these prompts in Claude Desktop:

What are the current weather alerts for California?

What's the weather forecast for New York City coordinates 40.7128, -74.0060?

Are there any active weather alerts for Texas?

🛠️ Available Tools

`get_alerts(state: str)`

Get active weather alerts for a US state.

Parameters:

state: Two-letter US state code (e.g., "CA", "NY", "TX")

Example:

Get weather alerts for Florida

`get_forecast(latitude: float, longitude: float)`

Get detailed weather forecast for specific coordinates.

Parameters:

latitude: Latitude coordinate
longitude: Longitude coordinate

Example:

What's the weather forecast for coordinates 34.0522, -118.2437?

🔍 Troubleshooting

Server Not Connecting

Check Python Path: Ensure the Python path in your config is correct
Verify File Path: Make sure the path to weather.py is absolute and correct
Restart Claude: Always restart Claude Desktop after config changes
Check Logs: Look at the log file for error messages

Common Issues

Issue: "Server disconnected"

Solution: Check that all dependencies are installed in the correct Python environment

Issue: "No module named 'mcp'"

Solution: Install MCP: pip install mcp

Issue: "File not found"

Solution: Use absolute paths in your configuration

Viewing Logs

Check the log file created in your project directory:

File: weather.log
Contains detailed error messages and request information

📁 Project Structure

weather-mcp-server/
├── weather.py              # Main MCP server
├── weather.log             # Log file (auto-generated)
├── README.md              # This file
├── LICENSE                # MIT License
└── .gitignore             # Git ignore patterns

🔧 How It Works

MCP Server: weather.py creates an MCP server using FastMCP
API Integration: Uses the National Weather Service API (no API key required)
Tools Registration: Exposes get_alerts and get_forecast as tools
Claude Integration: Claude Desktop connects via stdio transport

🚀 Extending This Project

This basic weather server can be extended with:

More Weather Data: Add hourly forecasts, radar data, etc.
Additional APIs: Integrate other weather services
Caching: Add response caching for better performance
Error Handling: Enhanced error recovery and retries
Configuration: Add config files for customization

📚 Learning Resources

📄 License

This project is licensed under the MIT License - see the file for details.

💡 Acknowledgments

Built with MCP (Model Context Protocol)
Weather data from National Weather Service API
Inspired by the need for accessible MCP learning resources

Happy coding! 🌟 If this project helped you learn MCP, please give it a star ⭐