Weather MCP Server 🌤️

A weather query server based on the Model Context Protocol (MCP), which can query weather information and forecasts based on the user's input address or automatically obtained current location.

Features ✨

• 🌍 Multiple Location Query Methods: Supports addresses, coordinates, and current location
• 🌤️ Real-time Weather Information: Retrieves detailed current weather data
• 📅 Weather Forecast: Supports 1-10 day future weather forecasts
• 📍 Geocoding: Conversion between addresses and coordinates
• 💡 Smart Suggestions: Provides lifestyle suggestions based on weather conditions
• 🌐 Multi-language Support: Chinese interface, supports global address queries
• 🔧 Easy Integration: Standard MCP protocol, compatible with various AI clients

Installation 🚀

1. Clone the Project

bash
git clone
cd weather-mcp-server

2. Install Dependencies

bash
npm install

3. Compile and Run

🎉 No API Key Required! This project uses the completely free Open-Meteo API, no registration or configuration of any keys is needed.

bash

Compile TypeScript

npm run build

Start the server

npm start

Or in development mode (with auto-recompilation)

npm run dev

Usage 📖

Using in Claude Desktop

1. Open the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the MCP server configuration:

json
{
"mcpServers": {
"weather": {
"command": "node",
"args": ["/path/to/weather-mcp-server/dist/index.js"]
}
}
}

1. Restart Claude Desktop

Using in Other MCP Clients

Refer to each client's documentation and connect to the server using the stdio transport protocol:

bash
node /path/to/weather-mcp-server/dist/index.js

Available Tools 🔧

1. get-weather-by-address

Fetches current weather information by address

Parameters:

• address (string): Address, e.g., "Beijing", "Pudong New Area, Shanghai", "New York"

Example:

Get the weather for Beijing

2. get-forecast-by-address

Fetches weather forecast by address

Parameters:

• address (string): Address
• days (number, optional): Number of days for the forecast, 1-10 days, default is 5 days

Example:

Get a 7-day weather forecast for Shanghai

3. get-current-location-weather

Fetches weather information for the current location (based on IP address)

Parameters: None

Example:

Get the weather for my current location

4. get-current-location-forecast

Fetches weather forecast for the current location

Parameters:

• days (number, optional): Number of days for the forecast, 1-10 days, default is 5 days

Example:

Get a 3-day weather forecast for my current location

5. get-weather-by-coordinates

Fetches weather information by latitude and longitude coordinates

Parameters:

• latitude (number): Latitude, between -90 and 90
• longitude (number): Longitude, between -180 and 180

Example:

Get the weather information for coordinates (39.9042, 116.4074)

6. geocode-address

Converts an address to latitude and longitude coordinates

Parameters:

• address (string): The address to be parsed

Example:

Parse the coordinates for "Tiananmen Square"

Available Resources 📚

weather://status

Displays the configuration status and availability of the weather service

Available Prompts 🎯

weather-assistant

Weather query smart assistant

Parameters:

• location (string, optional): Location information
• query_type (enum, optional): Query type, "current" or "forecast"

Example Output 📋

Weather Information Example

📍 Location: Beijing, Beijing, China
🌡️ Temperature: 22°C (Feels like: 24°C)
🌤️ Weather: Clear
💧 Humidity: 45%
💨 Wind Speed: 12 km/h (SW)
🌡️ Pressure: 1013 mb
👁️ Visibility: 10 km
☀️ UV Index: 6
🕐 Updated: 2024-01-15 14:30

💡 Suggestions:
☀️ It's warm, wear light clothing
🧴 Strong UV, apply sunscreen

Weather Forecast Example

📍 Beijing, Beijing, China Weather Forecast

🌟 Current Weather:
Temperature: 22°C (Feels like: 24°C)
Weather: Clear
Humidity: 45% | Wind Speed: 12 km/h

📅 Forecast for the next few days:
Today (2024-01-15):
🌡️ 18°C ~ 25°C | Clear
💧 Humidity: 45% | 🌧️ Rain Probability: 10%

Tomorrow (2024-01-16):
🌡️ 16°C ~ 23°C | Partly Cloudy
💧 Humidity: 55% | 🌧️ Rain Probability: 20%## Technical Architecture 🏗️

Core Components

• WeatherService: Weather API calls and data formatting
• LocationService: Geolocation services and address resolution
• MCP Server: Server implementation based on the standard MCP protocol

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• axios: HTTP request library
• zod: Data validation
• dotenv: Environment variable management

API Providers

• Open-Meteo: Free weather data provider
• Open-Meteo Geocoding: Free geocoding service
• IP-API: Free IP address location service

Development 🛠️

Project Structure

weather-mcp-server/
├── src/
│ ├── index.ts # Main server file
│ ├── weather-service.ts # Weather service
│ ├── location-service.ts # Location service
│ └── types.ts # Type definitions
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
├── env.example
└── README.md

Development Commands

bash

Install dependencies

npm install

Development mode (auto-recompile)

npm run dev

Compile

npm run build

Run

npm start

Adding New Features

1. Add new methods in the corresponding service class
2. Register new tools, resources, or prompts in src/index.ts
3. Update type definitions (if needed)
4. Rebuild and test

Troubleshooting 🔧

Common Issues

1. Network Connection Problems

   • Check your network connection
   • Ensure firewall settings allow access to external APIs

2. Address Resolution Failure

   • Try using a more specific address
   • Check for correct spelling of the address

3. Compilation Errors

   • Ensure Node.js version >= 18.0.0
   • Delete node_modules and dist directories and reinstall

4. Service Temporarily Unavailable

   • Open-Meteo service may occasionally be under maintenance; please try again later

Debug Mode

Enable verbose logging:

bash
DEBUG=weather-mcp-server npm start

Contributing 🤝

Contributions are welcome! Please follow these steps:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Create a Pull Request

License 📄

This project is licensed under the MIT License. See the LICENSE file for details.

Support 💬

If you encounter any issues or have suggestions:

1. Check the Troubleshooting section
2. Search existing Issues
3. Create a new Issue and provide detailed information

Changelog 📝

v1.0.0

• Initial release
• Uses Open-Meteo free API, no key required
• Supports basic weather query functionality
• Supports address and coordinate queries
• Supports automatic detection of current location
• Supports weather forecasts (up to 16 days)
• Provides smart weather advice
• Completely free to use

---

Enjoy using the Weather MCP Server! 🌤️✨