bhaveshxop/Build-your-first-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

1. Completely close Claude Desktop
2. Reopen Claude Desktop
3. 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

1. Check Python Path: Ensure the Python path in your config is correct
2. Verify File Path: Make sure the path to weather.py is absolute and correct
3. Restart Claude: Always restart Claude Desktop after config changes
4. 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

1. MCP Server: weather.py creates an MCP server using FastMCP
2. API Integration: Uses the National Weather Service API (no API key required)
3. Tools Registration: Exposes get_alerts and get_forecast as tools
4. 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

• MCP Documentation
• Claude Desktop MCP Guide
• National Weather Service API

📄 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 ⭐