Python Simple MCP Tutorial

This project demonstrates a simple weather server using the mcp library. It exposes a tool that returns real weather data for a given location using the OpenWeatherMap API.

MCP (Model Context Protocol) is a universal standard that enables AI agents (LLMs) to access data, tools and services. In this case, we will build a “server” that fetches real weather data for an LLM to interact with.

Setting Up

This project uses uv for package management. Go here for instructions on how to install uv.

uv venv

Activate the virtual environment:

source .venv/bin/activate

Install dependencies.

uv sync

API Key Setup

This project uses the OpenWeatherMap API to fetch real weather data. You’ll need to:

1. Sign up for a free account at OpenWeatherMap
2. Get your API key from the dashboard
3. Set the environment variable:

export OPENWEATHER_API_KEY=your_api_key_here

How To Run

To test the weather MCP server, execute the following command:

mcp dev src/mcp_weather.py

Then wait a while for to load, and click the link to “open inspector with token pre-filled”. This will give you a UI you can use to test the MCP server right in your browser.

Deep Dive

How does our AI agent know how to use this MCP tool? Well, in short, it gets serialized into a JSON schema.

FastMCP automatically registers the get_weather function as a tool, extracting the schema from the function signature and docstring.

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" }
    },
    "required": ["location"]
  }
}

Then, the AI agent that we use (e.g. Claude Desktop, Cursor, or our own implementation) will know about these tools and know how to invoke them via prompt engineering. It will be turned into a prompt similar to this:

You have access to these tools:
- get_weather: Get current weather for a location

To use: {"name": "get_weather", "parameters": {"location": "Tokyo"}}

MCP Clients: Interacting with MCP Servers

If you want your AI agent to interact with MCP servers, you need an MCP client. Some UI tools (Claude Desktop and Cursor) have this built-in for you already. But you can do this programmatically via code as well.

What it usually boils down to is declaring your MCP server in a config file with instructions on how to access it. In the case of Claude Desktop, it looks something like this:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "[...]", "/[PATH_TO_PROJECT]/src/mcp_weather.py"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}