mcp-caiyun-weather

This MCP server exposes a Caiyun Weather integration that leverages Caiyun's Weather API to provide real-time weather data, forecasts, historical weather, and weather alerts. To use it, you must supply a Caiyun Weather API token via the CAIYUN_WEATHER_API_TOKEN environment variable. The server offers the following tools: get_realtime_weather (fetches current conditions for a given longitude and latitude, including temperature, humidity, wind, precipitation, air quality metrics, AQI, and life indices), get_hourly_forecast (hour-by-hour forecast for the next 72 hours), get_weekly_forecast (daily forecast for the next 7 days), get_historical_weather (past 24 hours data), and get_weather_alerts (current alerts for a location). Each tool requires lng and lat as inputs. Use these tools by calling the corresponding command names in your MCP client (e.g., Claude Desktop) and passing the required parameters. Remember to set CAIYUN_WEATHER_API_TOKEN in the environment for authentication. The CLI integration is designed to be used inside Claude Desktop via the configured directory/run commands, enabling natural language prompts to fetch weather information for your chosen location.

Prerequisites:

• Access to Caiyun Weather API and an API token
• uv (or uvx) installed on your system
• Claude Desktop or MCP client capable of running the MCP server via UV/UVX

Step-by-step:

1. Install UV (required for running the Caiyun MCP server):

   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Obtain a Caiyun Weather API token from the Caiyun Weather API portal.

3. Configure the MCP server in Claude Desktop (production setup):

   • Create or edit claude_desktop_config.json with:

     { "mcpServers": { "caiyun-weather": { "command": "uvx", "args": ["mcp-caiyun-weather"], "env": { "CAIYUN_WEATHER_API_TOKEN": "YOUR_API_KEY_HERE" } } } }

4. Run the MCP server through Claude Desktop using the configuration above. In debugging mode, you can test with:

   npx @modelcontextprotocol/inspector
   uvx
   --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-caiyun-weather
   run
   mcp-caiyun-weather

5. For local development, point the uv command to your local mcp-caiyun-weather directory and run:

   uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-caiyun-weather run mcp-caiyun-weather

6. Ensure CAIYUN_WEATHER_API_TOKEN is set in your environment whenever you start the server.

Notes:

• The path in --directory must be the absolute path to the parent folder that contains the mcp-caiyun-weather project.
• If you modify environment variables, restart the MCP server to apply changes.

Tips and common issues:

• Ensure your Caiyun Weather API token is valid and has permissions for the endpoints used by these tools.
• Always set CAIYUN_WEATHER_API_TOKEN in the environment before starting the MCP server; without it, API calls will fail.
• When testing locally, use the --directory option to point to the exact folder containing the mcp-caiyun-weather module so UV can locate the server entrypoint.
• If you encounter API rate limits, consider scheduling requests or caching results where appropriate (within your MCP consumer or downstream tooling).
• The available tools expect lng (longitude) and lat (latitude) as inputs; supply them with precise decimal coordinates for best results.
• If you switch between production and development setups, remember to update the --directory path and environment variables accordingly.