# What is MCP? — sample code

Two **real, runnable MCP servers** for the video — one that **reads** the world and one
that **writes** to it — plus a **boilerplate template** to build your own. No API keys.
Runs on **Windows, macOS, and Linux**.

▶️ Video: _(link at publish)_ · 📬 Newsletter: _(link)_

## What's here
| File | Does | Shows |
|---|---|---|
| `weather_server.py` | live weather for any city (Open-Meteo, keyless) | a **read** tool — your AI reaching the real world |
| `tasks_server.py` | a to-do list it can add to / complete / list | **write** tools — your AI taking action and changing state |
| `server_template.py` | boilerplate to copy | how to build your own |
| `client.py` | tests both servers without Claude | |

## 1. Test it in 2 minutes (no Claude needed)
Install [uv](https://docs.astral.sh/uv/) (one line, any OS), then from this folder:
```bash
uv run python client.py
```
You'll see a read demo and a write demo:
```
weather_server.py  tools: ['get_weather']
  get_weather({'city': 'Tokyo'}) -> Tokyo, Japan: 21.7°C, mainly clear, wind 4.4 km/h.

tasks_server.py  tools: ['add_task', 'complete_task', 'list_tasks']
  add_task({'task': 'record episode 2'}) -> Added: 'record episode 2'  (you now have 1 task(s)).
  complete_task({'number': 1}) -> Completed: 'record episode 2'.
  list_tasks({}) -> 1. [x] record episode 2
```
The tasks server writes to a `tasks.json` right next to it — open the file and you'll
see exactly what your AI changed.

## 2. Connect them to Claude
- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`

```jsonc
{
  "mcpServers": {
    "weather": { "command": "uv", "args": ["--directory", "ABSOLUTE/PATH/TO/THIS/FOLDER", "run", "python", "weather_server.py"] },
    "tasks":   { "command": "uv", "args": ["--directory", "ABSOLUTE/PATH/TO/THIS/FOLDER", "run", "python", "tasks_server.py"] }
  }
}
```
Restart Claude, then try:
- **Read:** "What's the weather in Tokyo right now?"
- **Write:** "Add 'finish the thumbnail' to my tasks." → then "What's on my list?"

## 3. Build your own
Open `server_template.py`, rename the server, and replace `do_something` with your tool —
read a file, hit an API, write to a database. Uncomment the resource/prompt examples for
those too, then point Claude at it the same way.

## Read vs. write — and the one safety note
`weather_server` only **reads**. `tasks_server` **writes** (it changes `tasks.json`). That
write power — letting your AI actually *do* things — is the whole point of MCP. It's also
exactly why you only connect servers you trust, and why real tools add confirmations and
permissions before destructive actions.

## Why it's cross-platform
Pure Python + the standard library for HTTP (`urllib`), local files via `pathlib`, and
`sys.executable` to launch servers — no OS-specific paths or shells. Only dependency: the
`mcp` SDK.

MIT licensed. Built for the **AI Makes Sense** channel.