9meo/mcp-server-tutorial
If you are the rightful owner of mcp-server-tutorial and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Weather MCP Server provides weather information using the OpenMeteo API, integrated with Claude Desktop for natural language queries.
Weather MCP Server
A Model Context Protocol (MCP) server that provides weather information using the OpenMeteo API. This server integrates with Claude Desktop to allow natural language weather queries.
๐ฆ๏ธ Features
- Current Weather: Get real-time weather data for any location with coordinates
- Weather Forecast: 7-day weather forecast with temperature and precipitation data
- City Search: Quick weather lookup for major cities (Bangkok, Tokyo, New York, etc.)
- MCP Integration: Seamless integration with Claude Desktop and other MCP clients
- Error Handling: Robust error handling for SSL, network, and API issues
- Multiple Transports: Support for stdio, HTTP, and SSE transports
- Cross-Platform: Works on Windows, macOS, Linux, and WSL
๐ Quick Start
Option 1: Automated Setup
macOS:
curl -sSL https://raw.githubusercontent.com/9meo/mcp-server-tutorial/main/setup_mac.sh | bash
Linux/WSL:
curl -sSL https://raw.githubusercontent.com/9meo/mcp-server-tutorial/main/setup.sh | bash
Windows:
curl -sSL https://raw.githubusercontent.com/9meo/mcp-server-tutorial/main/setup.bat -o setup.bat && setup.bat
WSL (Windows Subsystem for Linux):
# Open WSL terminal and run:
curl -sSL https://raw.githubusercontent.com/9meo/mcp-server-tutorial/main/setup.sh | bash
Option 2: Manual Setup
Prerequisites
- Python 3.8 or higher
- Internet connection for API access
- For WSL users: WSL 2 recommended
Step-by-Step Installation
-
Install UV Package Manager
Linux/macOS/WSL:
curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc # or restart terminal
Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-
Create Project Directory
mkdir weather-mcp && cd weather-mcp uv init --name weather-mcp
-
Install Dependencies
uv add mcp httpx
-
Download Server Code
Copy the
weather_server.py
file from this repository, or create it manually with the provided code. -
Test Installation
# Test dependencies uv run python -c "import mcp, httpx; print('โ Dependencies installed successfully')" # Test the server uv run python weather_server.py
For WSL Users
WSL (Windows Subsystem for Linux) is fully supported and recommended for Windows users:
# 1. Open WSL terminal (Ubuntu/Debian recommended)
wsl
# 2. Update packages
sudo apt update && sudo apt install -y curl git
# 3. Follow Linux installation steps above
curl -LsSf https://astral.sh/uv/install.sh | sh
โ๏ธ Configuration
Claude Desktop Setup
-
Locate Configuration File:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
- macOS:
-
Choose Configuration Based on Your Setup:
Standard Installation (Linux/macOS/Windows):
{ "mcpServers": { "weather": { "command": "uv", "args": ["run", "--directory", "/absolute/path/to/weather-mcp", "python", "weather_server.py"], "env": { "SSL_VERIFY": "false" } } } }
WSL Configuration (Recommended for WSL users):
{ "mcpServers": { "weather": { "command": "wsl", "args": ["-e", "bash", "-c", "cd /home/[USERNAME]/weather-mcp && uv run python weather_server.py"], "env": { "SSL_VERIFY": "false" } } } }
WSL Alternative (Using Windows UNC paths):
{ "mcpServers": { "weather": { "command": "uv", "args": ["run", "--directory", "\\\\wsl$\\Ubuntu\\home\\[USERNAME]\\weather-mcp", "python", "weather_server.py"], "env": { "SSL_VERIFY": "false" } } } }
-
Important Notes:
- Replace
/absolute/path/to/weather-mcp
with your actual project path - Replace
[USERNAME]
with your actual username - Use forward slashes
/
for Unix paths, backslashes\\
for Windows paths - Restart Claude Desktop after making changes
- Replace
Getting Your Project Path
Linux/macOS/WSL:
cd weather-mcp && pwd
Windows:
cd weather-mcp && echo %cd%
Environment Variables
SSL_VERIFY
: Set to"false"
to disable SSL verification (useful in corporate environments with proxy servers)
๐ ๏ธ Available Tools
get_current_weather(latitude, longitude)
Get current weather conditions for specified coordinates.
Parameters:
latitude
(float): Latitude of the locationlongitude
(float): Longitude of the location
Example:
await get_current_weather(13.7563, 100.5018) # Bangkok
get_forecast(latitude, longitude)
Get 7-day weather forecast for specified coordinates.
Parameters:
latitude
(float): Latitude of the locationlongitude
(float): Longitude of the location
get_weather_by_city(city_name)
Get current weather by city name (supports major cities).
Parameters:
city_name
(str): Name of the city
Supported Cities:
- Bangkok, Tokyo, New York, London, Paris, Singapore, Sydney, Los Angeles
๐ Resources
weather://popular-cities
Returns a list of popular cities with their coordinates that are supported by the get_weather_by_city
tool.
๐ง Development
Project Structure
weather-mcp/
โโโ weather_server.py # Main MCP server implementation
โโโ test_server.py # Comprehensive test suite
โโโ pyproject.toml # Project configuration and dependencies
โโโ Makefile # Development commands
โโโ Dockerfile # Container deployment
โโโ setup.sh # Linux/macOS setup script
โโโ setup.bat # Windows setup script
โโโ README.md # This documentation
โโโ QUICK_START.md # Quick setup guide
โโโ .github/workflows/test.yml # CI/CD pipeline
โโโ .vscode/ # VS Code configuration
โ โโโ settings.json # Editor settings
โ โโโ launch.json # Debug configuration
โโโ .gitignore # Git ignore rules
โโโ .venv/ # Virtual environment (created by UV)
Development Commands
Using Make (Linux/macOS/WSL):
# Install dependencies
make install
# Run tests
make test
# Start server
make run
# Format code
make format
# Run linting
make lint
# Run all checks
make check
# Start MCP Inspector
make inspector
# Quick development setup
make dev-install
Using UV directly:
# Install dependencies
uv sync
# Add development dependencies
uv add --dev pytest pytest-asyncio black isort mypy
# Run tests
uv run python test_server.py
# Start server
uv run python weather_server.py
# Format code
uv run black weather_server.py test_server.py
uv run isort weather_server.py test_server.py
# Type checking
uv run mypy weather_server.py test_server.py
Running Tests
Comprehensive Test Suite:
# Run all tests
uv run python test_server.py
# Expected output:
# ๐งช Weather MCP Server Test Suite
# โ
Import tests passed
# โ
API connectivity working
# โ
Current weather function working
# โ
Weather forecast function working
# โ
City weather function working
# โ
Error handling working
# ๐ All tests passed!
Individual Tests:
# Test dependencies only
uv run python -c "import mcp; import httpx; print('โ
Dependencies OK')"
# Test API connectivity only
uv run python -c "
import asyncio, httpx
async def test():
async with httpx.AsyncClient() as client:
response = await client.get('https://api.open-meteo.com/v1/forecast?latitude=13.7563&longitude=100.5018¤t=temperature_2m')
print('โ
API connectivity OK' if response.status_code == 200 else 'โ API error')
asyncio.run(test())
"
Docker Development
Build and Run:
# Build image
docker build -t weather-mcp .
# Run container
docker run -it --rm weather-mcp
# Development with volume mount
docker run -it --rm -v $(pwd):/app weather-mcp bash
VS Code Setup
The project includes VS Code configuration for optimal development experience:
- Install recommended extensions (Python, WSL if applicable)
- Open project in VS Code:
code weather-mcp
- Select Python interpreter: Choose the UV virtual environment
- Use debugging: F5 to start with breakpoints
Code Quality
Formatting:
- Black: Code formatting
- isort: Import sorting
Linting:
- mypy: Static type checking
- VS Code: Real-time error detection
Testing:
- pytest: Unit testing framework
- Custom test suite: Integration testing
๐ Troubleshooting
Common Issues
1. SSL Certificate Errors
Symptoms: certificate verify failed
or SSL connection errors
Solutions:
# Option 1: Disable SSL verification (development only)
export SSL_VERIFY=false
# Option 2: Use corporate CA bundle
export SSL_CERT_FILE=/path/to/corporate-ca-bundle.crt
# Option 3: Update certificates
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates
# macOS
brew install ca-certificates
2. Module Not Found Errors
Symptoms: ModuleNotFoundError: No module named 'mcp'
or similar
Solutions:
# Ensure virtual environment is activated and dependencies installed
uv sync
# Check installation
uv show mcp
uv show httpx
# Reinstall if needed
uv add --force mcp httpx
3. Claude Desktop Can't See Tools
Symptoms: Claude doesn't respond to weather queries or can't find tools Solutions:
- โ
Verify absolute paths in
claude_desktop_config.json
- โ Check JSON syntax is valid (use online JSON validator)
- โ Restart Claude Desktop after configuration changes
- โ
Test server independently:
uv run python weather_server.py
4. WSL-Specific Issues
Symptoms: Commands not found or path issues in WSL Solutions:
# Check WSL version
wsl --version
# Update WSL
wsl --update
# Check if UV is in PATH
which uv
echo $PATH
# Reinstall UV if needed
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
5. API Request Failures
Symptoms: "Unable to fetch weather data" messages Solutions:
# Test API connectivity directly
curl "https://api.open-meteo.com/v1/forecast?latitude=13.75&longitude=100.5¤t=temperature_2m"
# Check firewall/proxy settings
ping api.open-meteo.com
# Test with timeout
curl --max-time 10 "https://api.open-meteo.com/v1/forecast?latitude=0&longitude=0¤t=temperature_2m"
6. Permission Issues (Linux/macOS/WSL)
Symptoms: Permission denied errors Solutions:
# Make script executable
chmod +x weather_server.py
# Check directory permissions
ls -la weather_server.py
# Fix ownership if needed
sudo chown $USER:$USER weather_server.py
Debug Mode & Logging
Enable Debug Logging:
# Add to weather_server.py
import logging
logging.basicConfig(level=logging.DEBUG)
Check Logs:
- Claude Desktop Logs:
- macOS:
~/Library/Logs/Claude/
- Windows:
%APPDATA%/Claude/logs/
- macOS:
- Server Output: Check terminal where you ran the server
Test Server Independently:
# Run server and test tools manually
uv run python test_server.py
# Use MCP Inspector for GUI testing
npx @modelcontextprotocol/inspector uv run python weather_server.py
Getting Help
- Check this README for common solutions
- Review Claude Desktop logs for specific errors
- Test server independently to isolate issues
- Verify API connectivity with curl commands
- Check GitHub Issues for similar problems
If you're still having issues:
- ๐ Open an issue with detailed error information
- ๐ Include your OS, Python version, and error logs
- ๐ Mention if you're using WSL or corporate network
๐ค Usage Examples
Once configured with Claude Desktop, you can interact using natural language:
Basic Weather Queries
- "What's the weather in Bangkok?"
- "Show me the current temperature in Tokyo"
- "How's the weather at coordinates 40.7128, -74.0060?" (New York)
Forecast Queries
- "Can you get the 7-day forecast for London?"
- "What will the weather be like in Singapore this week?"
- "Show me the forecast for Paris for the next few days"
Supported Cities (via get_weather_by_city
tool)
- Bangkok, Tokyo, New York, London, Paris, Singapore, Sydney, Los Angeles
Advanced Queries
- "Compare the weather between Bangkok and Tokyo"
- "What's the humidity in New York right now?"
- "Will it rain in London this week?"
Example Interaction
User: "What's the weather like in Bangkok right now?"
Claude: I'll check the current weather in Bangkok for you.
[Claude calls get_current_weather(13.7563, 100.5018)]
Based on the current weather data for Bangkok:
๐ก๏ธ **Temperature**: 32ยฐC
๐ง **Humidity**: 65%
๐ฆ๏ธ **Conditions**: Partly cloudy
๐ง **Precipitation**: 0mm
The weather in Bangkok is warm and humid with partly cloudy skies.
๐ Technical Details
API Integration
- Data Source: OpenMeteo API - Free weather API with no API key required
- Update Frequency: Real-time data with hourly updates
- Coverage: Global weather data for any coordinates
- Rate Limits: Fair use policy, no authentication required
MCP Protocol Features
- Transport: stdio (for Claude Desktop), HTTP and SSE also supported
- Tools: 3 weather-related tools exposed to Claude
- Resources: Popular cities list for reference
- Error Handling: Graceful fallbacks and informative error messages
Performance & Reliability
- Timeout: 30-second request timeout
- Retry Logic: Built-in error handling for network issues
- SSL Support: Configurable SSL verification
- Async: Non-blocking async/await implementation
๐ Platform-Specific Notes
Windows Users
- Recommended: Use WSL for better performance and compatibility
- Alternative: Native Windows installation works but may have SSL issues in corporate environments
- Path Format: Use backslashes
\
or double backslashes\\
in config files
macOS Users
- Homebrew: Can install UV via
brew install uv
- Path Format: Use forward slashes
/
in config files - Permissions: May need to allow terminal access in System Preferences
Linux Users
- Package Managers: UV available in most package repositories
- Dependencies: May need to install
curl
,git
, andbuild-essential
- Permissions: Ensure proper file permissions with
chmod +x
WSL Users (Recommended for Windows)
- Performance: Better than native Windows for Python development
- Compatibility: Full Linux compatibility
- Integration: Easy VS Code integration with WSL extension
- Configuration: Use either WSL commands or UNC paths in Claude config
๐ Quick Commands Reference
Setup
# One-line setup (Linux/macOS/WSL)
curl -sSL https://raw.githubusercontent.com/your-repo/weather-mcp/main/setup.sh | bash
# Manual setup
mkdir weather-mcp && cd weather-mcp
uv init && uv add mcp httpx
# Copy weather_server.py and configure Claude Desktop
Testing
# Test everything
make test # or: uv run python test_server.py
# Test specific components
uv run python -c "import mcp, httpx; print('โ
OK')"
make inspector # GUI testing tool
Running
# Start server
make run # or: uv run python weather_server.py
# Debug mode
DEBUG=true uv run python weather_server.py
Development
# Format code
make format # or: uv run black . && uv run isort .
# Type checking
make lint # or: uv run mypy weather_server.py
# All checks
make check
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Related Links
- ๐ Model Context Protocol Documentation - Official MCP docs
- ๐ MCP Python SDK - Python implementation
- ๐ค๏ธ OpenMeteo API - Weather data source
- โก UV Package Manager - Fast Python package manager
- ๐ช WSL Documentation - Windows Subsystem for Linux
- ๐ค Claude Desktop - AI assistant with MCP support
๐ค Contributing
We welcome contributions! Here's how to get started:
- Fork the repository on GitHub
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and add tests if applicable
- Run the test suite:
make check
oruv run python test_server.py
- Commit your changes:
git commit -m 'Add amazing feature'
- Push to your branch:
git push origin feature/amazing-feature
- Open a Pull Request with a clear description
Development Guidelines
- Follow existing code style (use
make format
) - Add tests for new functionality
- Update documentation as needed
- Ensure all tests pass (
make test
)
๐ Support & Community
Getting Help
- ๐ Check this README for comprehensive documentation
- ๐ Search existing issues on GitHub
- ๐ฌ Open a new issue with detailed information including:
- Operating system and version
- Python version (
python --version
) - UV version (
uv --version
) - Complete error messages and logs
- Steps to reproduce the issue
Community
- ๐ฌ GitHub Discussions - Ask questions and share ideas
- ๐ GitHub Issues - Report bugs and request features
- ๐ MCP Community - Join the broader MCP ecosystem discussions
Reporting Issues
When reporting issues, please include:
- Environment: OS, Python version, WSL if applicable
- Installation method: Automatic script vs manual
- Error logs: Complete error messages
- Steps to reproduce: What you did before the error occurred
- Expected behavior: What should have happened
Made with โค๏ธ for the MCP community
Star โญ this repository if you find it helpful!