{"id":"c8217216-0aa6-422b-a213-277db621b96c","slug":"mcp-simple-weather","kind":"mcp","name":"mcp-simple-weather","summary":"","owner":"kishor-aracreate","repoUrl":"https://github.com/kishor-aracreate/mcp-simple-weather","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-09-16T05:50:06.000Z","addedAt":"2026-10-21T19:37:57.734Z","logoUrl":"https://avatars.githubusercontent.com/u/227116923?u=3ff55cf4a7aad50a938a10e20231b1dfd3213899&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-24T11:55:12.050Z","sample":false,"url":"https://conduits.dev/tools/mcp-simple-weather","language":"Python","transports":["stdio"],"install":{"pypi":"weather"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Simple Weather MCP Server\n\nA simplified Model Context Protocol (MCP) server that provides weather data through integration with the National Weather Service API, designed to work with AI language models like Google's Gemini.\n\n## Features\n\n- **Weather Forecasts**: Get detailed weather forecasts for any location using latitude/longitude coordinates\n- **Weather Alerts**: Retrieve active weather alerts for US states\n- **MCP Protocol**: Implements JSON-RPC 2.0 based Model Context Protocol for AI integration\n- **Cross-platform**: Works on Windows, macOS, and Linux\n- **No External Dependencies**: Uses Python standard library only (urllib instead of external HTTP libraries)\n\n## Files\n\n- `weather_simple.py` - The MCP weather server implementation\n- `client_simple.py` - Simplified MCP client with Gemini API integration\n- `test_simple.py` - Test script to verify server functionality\n\n## Requirements\n\n- Python 3.8 or higher\n- Google Gemini API key (for client usage)\n- Internet connection (for National Weather Service API access)\n\n## Installation\n\n1. Clone or download the project files\n2. No additional Python packages required - uses standard library only\n3. Set your Gemini API key:\n   ```bash\n   export GEMINI_API_KEY=\"your-api-key-here\"\n   ```\n\n## Usage\n\n### Testing the Server\n\nFirst, test that the server works correctly:\n\n```bash\npython test_simple.py\n```\n\nExpected output:\n```\n✓ Server started successfully\n✓ Server initialization successful  \n✓ Found 2 tools:\n   - get_alerts: Get weather alerts for a US state.\n   - get_forecast: Get weather forecast for a location.\n```\n\n### Running the Client\n\nStart the interactive client:\n\n```bash\npython client_simple.py\n```\n\n### Connecting to Weather Server\n\nIn the client interface:\n\n```bash\nsimple-mcp> /connect weather python weather_simple.py\n```\n\n### Available Commands\n\n- `/connect <name> <command...>` - Connect to MCP server\n- `/disconnect <name>` - Disconnect from server  \n- `/list <name>` - List available tools\n- `/call <name> <tool> <json_args>` - Call a specific tool\n- `/servers` - List connected servers\n- `/quit` - Exit client\n\n### Tool Examples\n\n#### Get Weather Forecast\n```bash\nsimple-mcp> /call weather get_forecast {\"latitude\": 40.7128, \"longitude\": -74.0060}\n```\n\n#### Get Weather Alerts\n```bash\nsimple-mcp> /call weather get_alerts {\"state\": \"NY\"}\n```\n\n#### Natural Language Queries\nOnce connected, you can ask natural language questions:\n```bash\nsimple-mcp> What's the weather forecast for New York City?\nsimple-mcp> Are there any weather alerts for California?\n```\n\n## API Details\n\n### Available Tools\n\n#### get_forecast\nGets weather forecast for a specific location.\n\n**Parameters:**\n- `latitude` (float): Latitude coordinate\n- `longitude` (float): Longitude coordinate\n\n**Returns:** Formatted weather forecast text\n\n#### get_alerts  \nGets active weather alerts for a US state.\n\n**Parameters:**\n- `state` (string): Two-letter US state code (e.g., \"CA\", \"NY\", \"TX\")\n\n**Returns:** Formatted weather alerts text\n\n## Data Source\n\nThis server uses the [National Weather Service API](https://www.weather.gov/documentation/services-web-api), which provides:\n- Free access to US weather data\n- No API key required\n- Reliable, official weather information\n- Coverage for all US states and territories\n\n## Architecture\n\nThe server implements a simplified version of the Model Context Protocol:\n- **JSON-RPC 2.0**: Standard protocol for communication\n- **Stdio Transport**: Communication via standard input/output\n- **Async Processing**: Non-blocking request handling\n- **Error Handling**: Graceful handling of network and API errors\n\n## Troubleshooting\n\n### Server Won't Start\n- Ensure Python 3.8+ is installed\n- Check that no other process is using the same ports\n- Verify internet connectivity for NWS API access\n\n### Connection Timeouts\n- The server may take a few seconds to start\n- Check firewall settings if running across network\n- Ensure the server process hasn't crashed (check stderr output)\n\n### API Errors\n- NWS API may be temporarily unavailable\n- Some coordinates may be outside NWS coverage area\n- Invalid state codes will return no results\n\n### Client Issues\n- Ensure GEMINI_API_KEY environment variable is set\n- Check that Gemini API key is valid and has quota remaining\n- Verify network connectivity for both NWS and Gemini APIs\n\n## Limitations\n\n- **US Only**: National Weather Service API only covers US locations\n- **Coordinate Precision**: NWS API requires fairly precise coordinates\n- **Rate Limiting**: NWS API has undocumented rate limits\n- **Forecast Range**: Limited to 5-day forecast periods\n\n## Development\n\n### Extending the Server\n\nTo add new tools, follow this pattern in `weather_simple.py`:\n\n```python\n@server.tool(\"tool_name\")\nasync def tool_function(param1: str, param2: float) -> str:\n    \"\"\"Tool description for AI context.\n    \n    Args:\n        param1: Description of parameter\n        param2: Description of parameter\n    \"\"\"\n    # Implementation here\n    return \"Result string\"\n```\n\n### Custom Clients\n\nThe server implements standard JSON-RPC 2.0 over stdio, so you can create custom clients in any language. Key methods:\n- `initialize` - Start session\n- `tools/list` - Get available tools\n- `tools/call` - Execute a tool\n\n## License\n\nThis project is provided as-is for educational and development purposes. The National Weather Service API is a public service provided by NOAA.\n\n"}