MCP

🚀 Weather MCP Server 🌤️

A weather query server based on the Model Context Protocol (MCP) that can query weather information and forecasts according to the address entered by the user or automatically obtain the current location.

✨ Features

• 🌍 Multiple location query methods: Supports address, coordinates, and current location.
• 🌤️ Real-time weather information: Obtain detailed current weather data.
• 📅 Weather forecast: Supports 1 - 10 days of future weather forecasts.
• 📍 Geocoding: Conversion between addresses and coordinates.
• 💡 Intelligent suggestions: Provide living suggestions based on weather conditions.
• 🌐 Multilingual support: Chinese interface, supports global address queries.
• 🔧 Easy to integrate: Standard MCP protocol, compatible with various AI clients.

📦 Installation

1. Clone the project

git clone <repository-url>
cd weather-mcp-server

2. Install dependencies

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 required.

# Compile TypeScript
npm run build

# Start the server
npm start

# Or development mode (auto recompile)
npm run dev

📚 Documentation

Use 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 MCP server configuration:

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

3. Restart Claude Desktop

Use in other MCP clients

Refer to the documentation of each client and use the stdio transport protocol to connect to the server:

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

🔧 Available Tools

1. get-weather-by-address

Get current weather information based on the address.

Parameters:

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

Example:

Get the weather in Beijing.

2. get-forecast-by-address

Get the weather forecast based on the address.

Parameters:

• address (string): Address.
• days (number, optional): Forecast days, 1 - 10 days, default is 5 days.

Example:

Get the 7-day weather forecast for Shanghai.

3. get-current-location-weather

Get the weather information of the current location (based on IP address).

Parameters: None

Example:

Get the weather at my current location.

4. get-current-location-forecast

Get the weather forecast of the current location.

Parameters:

• days (number, optional): Forecast days, 1 - 10 days, default is 5 days.

Example:

Get the 3-day weather forecast for my current location.

5. get-weather-by-coordinates

Get weather information based on latitude and longitude coordinates.

Parameters:

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

Example:

Get the weather information at coordinates (39.9042, 116.4074).

6. geocode-address

Convert an address to latitude and longitude coordinates.

Parameters:

• address (string): The address to be parsed.

Example:

Parse the coordinates of "Tiananmen Square".

📚 Available Resources

weather://status

Display the configuration status and availability of the weather service.

🎯 Available Prompts

weather-assistant

Intelligent weather query 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: Sunny
💧 Humidity: 45%
💨 Wind speed: 12 km/h (SW)
🌡️ Pressure: 1013 mb
👁️ Visibility: 10 km
☀️ UV index: 6
🕐 Last updated: 2024-01-15 14:30

💡 Suggestions:
☀️ It's quite hot, wear light clothing.
🧴 The UV is strong, it's recommended to apply sunscreen.

Weather forecast example

📍 Weather forecast for Beijing, Beijing, China

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

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

Tomorrow (2024-01-16):
  🌡️ 16°C ~ 23°C | Cloudy
  💧 Humidity: 55% | 🌧️ Chance of rain: 20%

🔧 Technical Details

Core components

• WeatherService: Weather API calls and data formatting.
• LocationService: Geolocation service and address parsing.
• 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 service 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

# Install dependencies
npm install

# Development mode (auto recompile)
npm run dev

# Compile
npm run build

# Run
npm start

Add new features

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

🔧 Troubleshooting

Common issues

1. Network connection issues
   • Check the network connection.
   • Make sure the firewall settings allow external API access.
2. Address parsing failure
   • Try using a more specific address.
   • Check if the address is spelled correctly.
3. Compilation errors
   • Make sure the Node.js version is >= 18.0.0.
   • Delete the node_modules and dist directories and reinstall.
4. Service temporarily unavailable
   • The Open-Meteo service may be under maintenance occasionally, please try again later.

Debug mode

Enable detailed logging:

DEBUG=weather-mcp-server npm start

🤝 Contribution

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, please:

1. Check the Troubleshooting section.
2. Search for existing Issues.
3. Create a new Issue and describe the problem in detail.

📝 Changelog

v1.0.0

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

Enjoy using the Weather MCP Server! 🌤️✨