OpenWeatherMap (Weekly Weather) MCP server for AI agents

The Weekly Weather MCP Server provides 8-day global weather forecasts and current weather conditions by leveraging OpenWeatherMap's One Call API 3.0. It allows AI assistants to access detailed weather information for any location, making it ideal for planning outdoor activities or providing weather-related recommendations.

Setup Instructions

Getting an OpenWeatherMap API Key

Register an account at OpenWeatherMap
Subscribe to the "One Call API 3.0" plan (free tier offers 1,000 API calls per day)
Wait for API key activation (can take up to an hour)

Installation

# Clone the repository
git clone https://github.com/rossshannon/weekly-weather-mcp.git
cd weekly-weather-mcp

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate  # Windows

# Install dependencies
pip3 install -r requirements.txt

Running the Server

Method 1: Using Environment Variables

# Set environment variables
export OPENWEATHER_API_KEY="your_api_key"  # Linux/Mac
set OPENWEATHER_API_KEY=your_api_key  # Windows

# Run the server
python weather_mcp_server.py

Method 2: Provide API Key When Calling

python weather_mcp_server.py

When using this method, you'll need to provide the api_key parameter in your requests.

MCP Client Configuration

Add this configuration to your MCP-supported client (Claude Desktop, Cursor, etc.):

{
  "weather_forecast": {
    "command": "python3",
    "args": [
      "/full_path/weather_mcp_server.py"
    ],
    "env": {
      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
    },
    "disabled": false,
    "autoApprove": ["get_weather", "get_current_weather"]
  }
}

If using a virtual environment, specify the full path to Python:

{
  "weather_forecast": {
    "command": "/full_path/venv/bin/python3",
    "args": [
      "/full_path/weather_mcp_server.py"
    ],
    "env": {
      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
    },
    "disabled": false,
    "autoApprove": ["get_weather", "get_current_weather"]
  }
}

Available Tools

get_weather

Provides comprehensive weather data including current conditions, hourly forecasts (48 hours), and 8-day forecasts with detailed information.

Parameters:

location: Location name (e.g., "Beijing", "New York,US", "Portland,OR,US")
api_key: OpenWeatherMap API key (optional if set as environment variable)
timezone_offset: Timezone offset in hours (default: 0 for UTC)

Ideal for questions like:

"Which days this week should I go for a run?"
"When's the best evening to work in my garden?"
"What's the windiest day coming up for flying a kite?"

get_current_weather

Returns only current weather conditions for a specified location.

Parameters: Same as get_weather

Usage Examples

Current Weather Example

User: What's the weather like in New York right now?

AI: Let me check the current weather in New York for you. [Calling get_current_weather("New York", timezone_offset=-4)]

Current weather in New York: 5°C, few clouds, humidity 42%, wind speed 4.1m/s.

Weekly Planning Example

User: I need to mow my lawn this week in Boston. Which day would be best?

AI: Let me check the weather forecast for Boston to find the best day for lawn mowing. [Calling get_weather("Boston", timezone_offset=-4)]

Looking at the Boston forecast for the week:

Today (Monday): Light rain (28% chance), 5°C
Tuesday: Clear, sunny, 10°C
Wednesday: Light rain (100% chance), 9°C
Thursday: Moderate rain (100% chance), 10°C
Friday: Moderate rain (100% chance), 11°C
Saturday: Partly cloudy, 13°C
Sunday: Scattered clouds, 17°C

Tuesday would be your best option for mowing the lawn. It will be clear and sunny with no chance of rain, and the temperature will be comfortable at around 10°C.

Troubleshooting

API Key Issues

Ensure you've subscribed to the "One Call API 3.0" plan
Allow time for API key activation (up to an hour)
Verify the API key is correctly set in environment variables or parameters

Location Issues

For ambiguous locations, include country codes (e.g., "Paris,FR" vs "Paris,TX,US")
For US cities, include state codes (e.g., "Portland,OR,US", "Portland,ME,US")
Check for typos in location names

Testing Your Setup

To verify your API key and installation before using with an MCP client:

export OPENWEATHER_API_KEY="your_api_key"
python3 test_mcp_client.py

If the test displays current weather data, your setup is working correctly.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.