mcp

# Weather MCP Server 🌤️ A weather query server based on Model Context Protocol (MCP), which can query weather information and forecasts based on the address entered by the user or automatically obtain the current location. ## Features ✨ - 🌍 **Multiple Location Query Methods**: Supports address, coordinates, current location - 🌤️ **Real-time Weather Information**: Get current detailed weather data - 📅 **Weather Forecast**: Supports 1-10 day future weather forecast - 📍 **Geocoding**: Conversion between address and coordinates - 💡 **Intelligent Suggestions**: Provides life suggestions based on weather conditions - 🌐 **Multi-language Support**: Chinese interface, supports global address query - 🔧 **Easy to Integrate**: Standard MCP protocol, compatible with various AI clients ## Installation 🚀 ### 1. Clone the project ```bash git clone <repository-url> 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, without registration or configuration of any keys. ```bash # Compile TypeScript npm run build # Start the server npm start # Or development mode (automatic recompilation) npm run dev ``` ## Usage 📖 ### 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: ```json { "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: ```bash node /path/to/weather-mcp-server/dist/index.js ``` ## Available Tools 🔧 ### 1. get-weather-by-address Get current weather information by address **Parameters:** - `address` (string): Address, e.g., "Beijing", "Shanghai Pudong New Area", "New York" **Example:** ``` Get the weather in Beijing ``` ### 2. get-forecast-by-address Get weather forecast by address **Parameters:** - `address` (string): Address - `days` (number, optional): Forecast days, 1-10 days, default 5 days **Example:** ``` Get the weather forecast for the next 7 days in Shanghai ``` ### 3. get-current-location-weather Get weather information for the current location (based on IP address) **Parameters:** None **Example:** ``` Get the weather at my current location ``` ### 4. get-current-location-forecast Get weather forecast for the current location **Parameters:** - `days` (number, optional): Forecast days, 1-10 days, default 5 days **Example:** ``` Get the weather forecast for the next 3 days at my current location ``` ### 5. get-weather-by-coordinates Get weather information by latitude and longitude coordinates **Parameters:** - `latitude` (number): Latitude, between -90 and 90 - `longitude` (number): Longitude, between -180 and 180 **Example:** ``` Get weather information for coordinates (39.9042, 116.4074) ``` ### 6. geocode-address Convert address to latitude and longitude coordinates **Parameters:** - `address` (string): Address to resolve **Example:** ``` Resolve the coordinates of "Tiananmen Square" ``` ## Available Resources 📚 ### weather://status Displays the configuration status and availability of the weather service ## Available Prompts 🎯 ### weather-assistant Weather query intelligent 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 at: 2024-01-15 14:30 💡 Suggestions: ☀️ The weather is hot, wear light clothing 🧴 The UV index is high, it is recommended to 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% | 🌧️ Precipitation probability: 10% Tomorrow (2024-01-16): 🌡️ 16°C ~ 23°C | Cloudy 💧 Humidity: 55% | 🌧️ Precipitation probability: 20% ``` ## Technical Architecture 🏗️ ### Core Components - **WeatherService**: Weather API calls and data formatting - **LocationService**: Geolocation service and address resolution - **MCP Server**: Server implementation based on 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/ # Compilation output ├── package.json ├── tsconfig.json ├── env.example └── README.md ``` ### Development Commands ```bash # Install dependencies npm install # Development mode (automatic recompilation) npm run dev # Compile npm run build # Run npm start ``` ### Adding New Features 1. Add a new method in the corresponding service class 2. Register new tools, resources, or prompts in `src/index.ts` 3. Update type definitions (if needed) 4. Recompile and test ## Troubleshooting 🔧 ### Common Issues 1. **Network Connection Issues** - Check network connection - Confirm that firewall settings allow external API access 2. **Address Resolution Failed** - Try using a more specific address - Check if the address spelling is correct 3. **Compilation Error** - Make sure Node.js version >= 18.0.0 - Delete the `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 detailed logs: ```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 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](LICENSE) file for details. ## Support 💬 If you encounter problems or have suggestions, please: 1. Check the [FAQ](#troubleshooting) 2. Search existing Issues 3. Create a new Issue and describe the problem in detail ## Changelog 📝 ### v1.0.0 - Initial version release - Uses Open-Meteo free API, no key required - Supports basic weather query functions - Supports address and coordinate queries - Supports automatic detection of current location - Supports weather forecast (up to 16 days) - Provides intelligent weather suggestions - Completely free to use --- **Enjoy using the Weather MCP Server!** 🌤️✨