Weather MCP Server & Client

A Model Context Protocol (MCP) implementation that exposes weather alerts from the National Weather Service API as tools. Includes an interactive chat client powered by Groq LLM and test scripts for both STDIO and SSE transports.

Table of Contents

• Prerequisites

• Setup

• Configuration Files

• Use Cases & How to Run

• Project Structure

• Troubleshooting

Prerequisites

• Python 3.13+ (see pyproject.toml)

• uv – Python package manager (install)

• Groq API Key – for the LLM (get one)

Setup

1. Clone or navigate to the project:

   cd /path/to/MCP

2. Create a with your Groq API key:

   GROQ_API_KEY=your_groq_api_key_here

3. Install dependencies with uv:

   uv sync

   This creates a .venv and installs all dependencies from pyproject.toml. The project uses langchain>=1.2.0,<2.0.0 for compatibility with mcp-use.

Configuration Files

Config Format

STDIO (command-based):

SSE (URL-based):

Use Cases & How to Run

All commands use uv run to execute scripts with the project's virtual environment and dependencies.

Case 1: Interactive Chat Client (STDIO)

Run an interactive chat that connects to the weather MCP server. The agent can call get_alerts when you ask about weather.

Run:

Commands:

• Type any question (e.g., "What are the weather alerts for California?")

• exit or quit – end the session

• clear – clear conversation history

What happens:

• Client reads server/weather_mcp.json

• Spawns uv run server/weather.py as a subprocess

• Communicates via stdin/stdout (stdio transport)

• Agent uses Groq LLM and calls get_alerts when needed

Case 2: STDIO Transport Test

Explicit test of the stdio transport. Same behavior as Case 2 but uses a dedicated config file.

Run:

What happens:

• Uses server/weather_stdio_config.json

• Client spawns uv run server/weather.py

• Runs one query and exits

Case 3: SSE Transport Test

Test the SSE (HTTP) transport. The script starts the server in HTTP mode, connects via URL, runs a query, then shuts down the server.

Run:

What happens:

1. Starts server/weather_sse.py in the background (listens on port 8000)

2. Waits for the server to be ready

3. Connects to http://127.0.0.1:8000/sse

4. Runs one query

5. Terminates the server process

Case 4: Run Weather Server Manually (SSE)

Run the weather server as a standalone HTTP process. Useful for debugging or when multiple clients need to connect.

Run:

Then in another terminal, use a client configured with url: "http://127.0.0.1:8000/sse" (e.g., test_weather_sse.py or a custom client with weather_sse_config.json).

Case 6: Run Weather Server Manually (STDIO)

Running the stdio server directly is rarely useful because it expects JSON-RPC on stdin. It's normally spawned by the client.

For debugging:

Project Structure

MCP Tools Exposed

MCP Resources

Troubleshooting

"No module named 'mcp_use'"

Run uv sync to install dependencies, then use uv run for all scripts:

"ModuleNotFoundError: No module named 'httpx'"

Dependencies are in pyproject.toml. Run uv sync to install.

"qwen-qwq-32b has been decommissioned"

The project uses llama-3.3-70b-versatile. If you see references to qwen-qwq-32b, update the model in the client/test scripts.

"Connection closed" or "Invalid JSON"

Avoid printing to stdout from code that runs in the MCP server process. Stdio uses stdin/stdout for JSON-RPC; any extra output breaks the protocol.

Port 8000 already in use

Stop the process using port 8000, or change the port in server/weather_sse.py:

Then update SSE_SERVER_PORT in test_weather_sse.py and the URL in weather_sse_config.json.

Sandbox / uv cache errors

Run with full permissions if you see "Operation not permitted" for uv cache: