hansobvius/mcp-server-example

Note: This example includes an update beyond the official tutorial — it uses a manifest.json so you can build an .mcpb bundle with mcpb pack command and upload/use the server without manually editing Claude's local claude_desktop_config.json. See the tutorial for context: https://modelcontextprotocol.io/docs/develop/build-server

MCP Weather Server (Python)

This project is a minimal Model Context Protocol (MCP) server exposing two weather tools: get_alerts and get_forecast. It was started from the Anthropic tutorial and adapted to use Conda for environment management and the MCP Bundle (mcpb) CLI to package the server for distribution.

Reference tutorial: Build an MCP server

Features

• get_alerts(state: str) -> str: Active NWS alerts for a US state (two-letter code).
• get_forecast(latitude: float, longitude: float) -> str: Next periods forecast for a US location.
• Runs over STDIO for compatibility with MCP hosts (e.g., Claude for Desktop).

Project layout

.
├─ main.py                       # Entry point that runs the MCP server (STDIO)
├─ manifest.json                 # MCP server manifest (used by bundling/hosts)
├─ mcp-server-demo.mcpb          # Example packaged bundle output (if built)
├─ server/
│  ├─ config.py                 # Server init, constants, FastMCP instance
│  ├─ tool.py                    # Tool implementations (alerts, forecast)
│  └─ helper.py                  # HTTP utils and alert formatting
└─ test/tools_test/              # Basic tests for the tools

Requirements

• Python 3.10+
• Conda (Anaconda/Miniconda)
• Network access to https://api.weather.gov

Python deps (installed inside the Conda env):

• mcp[cli] >= 1.2.0
• httpx
• (optional) pytest for tests

Setup (Conda)

On Windows PowerShell:

conda create -n mcp-weather python=3.11 -y
conda activate mcp-weather
pip install "mcp[cli]>=1.2.0" httpx pytest

Run locally (STDIO server)

python main.py

This runs an MCP server over STDIO. Do not use print() or other stdout logging in the server; use proper logging to stderr if you add logs, to avoid corrupting JSON-RPC messages. See tutorial guidance: Build an MCP server.

Package as an MCP Bundle (.mcpb)

This project is structured to be bundled with the MCP Bundle CLI (mcpb). The manifest.json describes how a host can run the server.

Examples:

# Pack the current project into an .mcpb file
mcpb pack --input . --output mcp-server-demo.mcpb

# Inspect the bundle metadata
mcpb inspect mcp-server-demo.mcpb

The resulting mcp-server-demo.mcpb can be uploaded or distributed to compatible MCP hosts/services that accept bundles.

Use with Claude for Desktop (Windows)

You can point Claude for Desktop to run the local project directly, or use the bundle if supported by your setup. To run directly from source, edit:

%APPDATA%\Claude\claude_desktop_config.json

Add (adjust paths as needed):

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "C:/ABSOLUTE/PATH/TO/mcp-server-demo/main.py"
      ]
    }
  }
}

Notes:

• Use an absolute path.
• Use forward slashes (/) or escape backslashes in JSON.
• Restart Claude for Desktop after editing the config.

Once configured, you should see the server’s tools available and be able to ask:

• “What are the active weather alerts in TX?”
• “What’s the forecast for 38.58, -121.49?”

Running tests

pytest -q

Implementation details

• Server init: server/config.py defines constants and the FastMCP instance named mcp-weather.
• Tools: server/tool.py registers get_alerts and get_forecast using the shared mcp instance.
• HTTP: server/helper.py uses httpx.AsyncClient with proper headers for NWS (User-Agent and Accept: application/geo+json).
• Entry point: main.py imports tools for side effects and calls mcp.run(transport='stdio').

Troubleshooting

• If tools don’t appear in your host, verify absolute paths and restart the host application.
• Ensure no stdout logging from the server process; prefer logging to stderr/files.
• For Claude for Desktop, check its logs for MCP issues (see the tutorial’s troubleshooting section).
• Ensure coordinates are within the US for NWS forecast endpoints.

License

MIT