MCP Notes Server — Your First MCP Server with Claude (Python)

A beginner-friendly, fully reproducible tutorial for building a Model Context Protocol (MCP) server in Python and connecting it to Claude.

The example server is a personal notes manager: Claude can create, list, read, search, update, and delete notes that are saved as Markdown files on your own computer.

📖 New to this? Follow the complete step-by-step guide in TUTORIAL.md. It explains every single command and shows the exact output you should see.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI apps like Claude talk to external programs. You write a small server exposing:

• Tools — actions Claude can take (e.g. "save a note")

• Resources — read-only data Claude can pull in (e.g. "all my notes")

Claude is the client: when you ask it something, it can decide to call your tools. Build the server once, and any MCP-aware app can use it.

Do I need to write a client too? Usually no — the client is an existing app like Claude Desktop or Claude Code. You only write a server. This repo includes an optional client.py purely to show what a client does under the hood; see TUTORIAL.md §9.

Related MCP server: Image Processor MCP Server

Quickstart

Requires uv (the tutorial shows how to install it). Then, from this folder:

# 1. Set up the environment (installs Python 3.12 + the MCP SDK, pinned)
uv sync

# 2. Test the server in the visual MCP Inspector
uv run mcp dev notes_server.py

To connect it to Claude Desktop, add this to your claude_desktop_config.json (use the absolute path from pwd):

{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/mcp_tutorial", "run", "notes_server.py"]
    }
  }
}

To connect it to Claude Code:

claude mcp add notes -- uv --directory "$(pwd)" run notes_server.py

Full details, expected output, and troubleshooting are in TUTORIAL.md.

Project structure

The tools

Plus a resource, notes://all, that returns every note concatenated.

Tested with

• uv 0.11.19

• Python 3.12.13 (pinned via .python-version)

• mcp 1.27.2

Because uv.lock and .python-version are committed, anyone who runs uv sync gets the exact same environment.

License

MIT — see LICENSE. Use it, fork it, teach with it.