Lesson 16 — Notes MCP Server

A Model Context Protocol (MCP) server that gives Claude a persistent personal notebook. Notes are stored on disk as JSON, so they survive restarts and are shared across every tool and resource — no stubbed responses.

• Stack: Python 3.10+ · official mcp SDK (FastMCP) · stdio transport

• Theme: Notes (recommended option)

Tools

(Satisfies the rubric: ≥2 tools, one with a required-only arg, one with an optional arg.)

Related MCP server: MCP Personal Tools Server

Resources

Storage

Notes live in a JSON file, default ~/.notes_mcp/notes.json. Override with the NOTES_DB_PATH environment variable (set in the Claude Desktop config below).

Setup

1. Install the dependency

# from this folder, using the course venv (or any Python 3.10+ env)
pip install "mcp[cli]"

2. (Optional) try it locally with the MCP Inspector

mcp dev server.py

This opens a local web inspector where you can call the tools and read the resources without Claude Desktop — handy for verifying everything works.

3. Connect to Claude Desktop

1. Install Claude Desktop from https://claude.ai/download

2. Open its config file (Claude Desktop → Settings → Developer → Edit Config, or directly at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

3. Merge in the contents of claude_desktop_config.json. Adjust the three absolute paths to match your machine:

   • command → your Python interpreter (the one where mcp is installed)

   • args[0] → the absolute path to server.py

   • env.NOTES_DB_PATH → where you want the notes file

4. Fully quit and reopen Claude Desktop. The notes server should appear under the tools (🔌 / hammer icon) in the chat input.

Example dialogs

1 — Add notes (required + optional args) 👤 Add a note "Buy oat milk and coffee beans" tagged shopping and groceries. 🤖 (calls add_note(text="Buy oat milk and coffee beans", tags=["shopping","groceries"])) Saved note #1. Tags: shopping, groceries. 👤 Also note "Read the MCP spec" — no tags. 🤖 (calls add_note(text="Read the MCP spec")) Saved note #2.

2 — Search & filter 👤 Which of my notes mention coffee? 🤖 (calls search_notes(query="coffee")) 1 match for 'coffee': #1 Buy oat milk and coffee beans [tags: shopping, groceries] 👤 Show me everything tagged shopping. 🤖 (calls list_notes(tag="shopping")) … lists note #1.

3 — Resource + cleanup 👤 Give me a summary of my notebook. 🤖 (reads the notes://stats resource) You have 2 notes; tags: shopping (1), groceries (1); most recent is "Read the MCP spec". 👤 Delete the shopping note. 🤖 (calls delete_note(note_id=1)) Deleted note #1.

(See examples/ for real screenshots of these in Claude Desktop.)

Known limitations

• Single-user, local only. One JSON file, no auth, no multi-user support. Concurrent writes from multiple server instances could race (last-write-wins); fine for a single Claude Desktop client.

• No full-text index. search_notes is a linear substring scan — perfectly fast for hundreds/thousands of notes, not meant for millions.

• No edit/update tool. You can add, search, list, and delete; editing means delete + re-add. (Easy to extend.)

• Plain substring search, not semantic — "groceries" won't match "food" unless that word is present.

• stdio transport only. Designed to be launched by Claude Desktop; not exposed as a network service.