kpirabaharan/MCP-Weather-Tutorial
If you are the rightful owner of MCP-Weather-Tutorial and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This repository provides a minimal client/server tutorial for working with weather data using the Model Context Protocol (MCP).
Weather Tutorial
This repository contains a minimal client/server tutorial for working with weather data. It is intended as a starting point for experiments, workshops, or self-paced learning.
Repository Layout
weather-mcp-client
– client-side project powering the user interface for the tutorial and automatically managing the server lifecycle when it runs.weather-mcp-server
– standalone server project that exposes APIs used by the client and can also be explored independently.
Getting Started (Client + Server)
- Install the dependencies for both projects following the instructions in their respective directories.
- Decide how you want the client to reach the server (stdio vs. HTTP) and follow the steps below.
- Point the client at the server instance if prompted.
Running the MCP Client
-
STDIO (single process)
- Activate the client virtual environment (
cd weather-mcp-client && source .venv/bin/activate
). - Launch the client with the server path:
uv run client.py ../weather-mcp-server/server.py
. - The client will spawn the server over stdio, so you do not need to start the server separately in this mode.
- Activate the client virtual environment (
-
HTTP (separate server process)
- Activate the server environment (
cd weather-mcp-server && source .venv/bin/activate
). - Start the server in HTTP mode, for example:
fastmcp run server.py:mcp --transport http --port 8000
(or adjust the command to your preferred runner/port). - Alternatively, build the Docker image in
weather-mcp-server/
(it defaults to stdio; pass--transport http ...
after the image name to host over HTTP). - In a second shell, activate the client environment and run:
uv run client.py http://localhost:8000/mcp
(setMCP_HTTP_HEADERS
if your server requires auth headers). - Because HTTP transport expects an already running server, confirm the server process is healthy before starting the client.
- Activate the server environment (
Standalone Server in VS Code
-
Add the server directory to your VS Code workspace (
File
→Add Folder to Workspace…
→ selectweather-mcp-server
). -
Install server dependencies (
uv venv && source .venv/bin/activate && uv sync
). -
Update your MCP configuration (
mcp.json
) so VS Code (or the MCP extension) can spawn the server:a) Launch with
uv
(default):{ "servers": { "weather": { "command": "uv", "args": ["run", "server.py"], "cwd": "/absolute/path/to/weather-tutorial/weather-mcp-server" } } }
Use an absolute
cwd
so the extension resolves the script reliably, and adjustcommand
/args
if you prefer a different launch method (for examplepython server.py
).b) Launch with Docker:
{ "servers": { "weather": { "command": "docker", "args": ["run", "--rm", "-i", "weather-mcp-server"], "cwd": "/absolute/path/to/weather-tutorial/weather-mcp-server" } } }
Build the image in
weather-mcp-server/
(docker build -t weather-mcp-server .
), and append extra flags toargs
(for example"-p", "8000:8000", "--", "--transport", "http", "--port", "8000"
) if you need the HTTP transport instead of stdio. -
Reload VS Code or the MCP extension so it picks up the updated configuration, then use the MCP panel to connect to the
weather
server for manual testing.
Contributing
Feel free to open issues or submit pull requests with improvements, bug fixes, or suggestions for additional tutorial steps. Please keep changes well-scoped and include any relevant tests or documentation updates.
License
This project is provided as-is for educational purposes. Adapt and extend it to suit your needs.