Weather MCP Server - Sample Implementation

Reference implementation for ASUS and OEM partners
A simple, production-ready MCP server demonstrating how to integrate external services with AI PCs using the Model Context Protocol.

License: MIT Node.js Version MCP SDK

🎯 Purpose

This sample MCP server demonstrates:

✅ How to create an MCP server from scratch
✅ How to expose tools (functions) to AI clients
✅ How to integrate external APIs (OpenWeather API)
✅ Production-ready error handling
✅ Clean, well-documented code

Perfect for: OEM partners building AI PC features, developers learning MCP, proof-of-concept projects

🌟 Features

Available Tools

get_current_weather - Get real-time weather for any city
- Temperature, conditions, humidity, wind speed
- Supports both Celsius and Fahrenheit
get_weather_forecast - Get 5-day forecast
- Daily high/low temperatures
- Weather conditions per day

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
OpenWeather API key (free tier available)

Installation

# Clone or download this repository cd weather-mcp-server # Install dependencies npm install # Configure API key cp .env.example .env # Edit .env and add your OpenWeather API key

Get API Key

Visit OpenWeather API
Sign up for free account
Generate API key
Add to .env file

Run the Server

# Start the server npm start # Or with auto-reload during development npm run dev

📖 Usage Examples

Configure in Claude Desktop

Add to your claude_desktop_config.json:

{ "mcpServers": { "weather": { "command": "node", "args": ["/absolute/path/to/weather-mcp-server/index.js"], "env": { "OPENWEATHER_API_KEY": "your_api_key_here" } } } }

Test with AI Client

Once configured, you can ask your AI assistant:

"What's the weather like in Taipei?" "Give me a 5-day forecast for Tokyo" "What's the temperature in New York in Fahrenheit?"

The AI will automatically call the appropriate MCP tools!

🏗️ Architecture

┌─────────────────┐ │ AI Client │ (Claude, ChatGPT, etc.) │ (Claude Desktop)│ └────────┬────────┘ │ MCP Protocol (stdio) ↓ ┌─────────────────┐ │ Weather MCP │ ← This server │ Server │ └────────┬────────┘ │ HTTPS ↓ ┌─────────────────┐ │ OpenWeather API │ └─────────────────┘

Key Components

index.js - Main server implementation
@modelcontextprotocol/sdk - Official MCP SDK
StdioServerTransport - Communicates via stdin/stdout
OpenWeather API - External weather data source

📁 Project Structure

weather-mcp-server/ ├── package.json # Dependencies and scripts ├── index.js # Main MCP server code ├── .env.example # Environment variables template ├── .env # Your API keys (git-ignored) ├── README.md # This file ├── README.zh-TW.md # 繁體中文版 ├── PARTNER-GUIDE.md # Detailed guide for OEM partners └── examples/ └── client-example.js # Example client code

🛠️ Development

Code Structure

The server is organized into clear sections:

Configuration - API keys, URLs
WeatherServer Class - Main server logic
Tool Registration - Define available tools
Tool Handlers - Implement tool functionality
Error Handling - Robust error management

Adding New Tools

// 1. Add tool definition in setupToolHandlers() { name: 'your_new_tool', description: 'What this tool does', inputSchema: { type: 'object', properties: { param1: { type: 'string', description: 'Parameter description' } }, required: ['param1'] } } // 2. Add handler in CallToolRequestSchema case 'your_new_tool': return await this.yourNewTool(args.param1); // 3. Implement the method async yourNewTool(param1) { // Your logic here return { content: [{ type: 'text', text: 'Result' }] }; }

🧪 Testing

Manual Testing

# Test the MCP server directly npm test

Integration Testing

Use the included examples/client-example.js to test tool calls programmatically.

📝 API Reference

Tool: `get_current_weather`

Parameters:

city (string, required) - City name (e.g., "Taipei", "Tokyo")
units (string, optional) - "metric" (default) or "imperial"

Returns:

🌤️ Current Weather in Taipei, TW Temperature: 25.3°C (feels like 26.1°C) Condition: Clear - clear sky Humidity: 65% Wind Speed: 3.2 m/s Pressure: 1013 hPa Visibility: 10.0 km Last updated: 11/14/2025, 10:30:00 AM

Tool: `get_weather_forecast`

Parameters:

city (string, required) - City name
units (string, optional) - "metric" (default) or "imperial"

Returns:

📅 5-Day Weather Forecast for Taipei, TW 11/14/2025: High: 26.5°C | Low: 22.1°C Condition: Clear 11/15/2025: High: 27.2°C | Low: 23.4°C Condition: Clouds ...

🔒 Security Best Practices

Implemented in this sample:

✅ API keys stored in environment variables (not in code)
✅ Input validation for all parameters
✅ Proper error handling (no sensitive data leakage)
✅ HTTPS for external API calls
✅ Minimal dependencies (reduces attack surface)

For production deployments:

🔐 Use secrets management system (AWS Secrets Manager, Azure Key Vault)
🔐 Implement rate limiting
🔐 Add request logging/monitoring
🔐 Use TLS for MCP communication if deployed remotely

🌐 Localization

This server supports multiple languages through the OpenWeather API:

// Add language parameter to API call const url = `${API_BASE_URL}/weather?q=${city}&units=${units}&lang=zh_tw&appid=${API_KEY}`;

Supported languages: en, zh_tw, zh_cn, ja, ko, and 50+ more

🐛 Troubleshooting

Common Issues

"City not found"

Check spelling of city name
Try including country code: "Taipei,TW"

"Weather API error: Unauthorized"

Verify your API key in .env
Check API key is active at openweathermap.org

"Module not found"

Run npm install
Check Node.js version >= 18.0.0

MCP server not detected in Claude

Verify claude_desktop_config.json path
Restart Claude Desktop
Check server logs for errors

📚 Learn More

MCP Resources

Weather API

🤝 For OEM Partners

See :

Detailed integration guide
Deployment options
Customization examples
Production checklist
Support information

Contact: partners@irisgo.ai

📄 License

MIT License - see LICENSE file

🙏 Credits

Created by: IrisGo.AI Team
MCP Protocol: Anthropic
Weather Data: OpenWeather
For: ASUS and AI PC OEM partners

📮 Support

Issues: GitHub Issues
Email: support@irisgo.ai
Documentation: docs.irisgo.ai

Last Updated: 2025-11-14 Version: 1.0.0