DEV Community

bradraylucas-eng
bradraylucas-eng

Posted on

I built a tiny MCP notes server in Python — here's the whole thing, free

#mcp #ai #opensource #python

Most MCP (Model Context Protocol) examples are either toy "hello world" servers or sprawling frameworks. I wanted the smallest useful thing: a notes server an AI assistant can actually use — create a note, list notes, search notes — backed by a plain local JSON file. No database, no cloud, no account.

It's open source (MIT) and free:

What it does

Three tools, that's it:

  • create_note(title, body, tags) — appends a note with an ISO timestamp
  • list_notes(limit) — newest first
  • search_notes(query) — case-insensitive substring search over title, body, and tags

Notes live in a local notes.json. Saves are atomic (write to temp file, then rename), so a crash mid-write can't corrupt your notes.

Two bugs worth knowing about

Building this surfaced two things that will bite anyone shipping an MCP server:

1. Same-second timestamps sort wrong. If two notes are created within the same second, sorting by timestamp alone gives you unstable order. Fix: keep a monotonically increasing insertion index and sort by (created_at, index). Boring, but your "list newest first" will silently lie to you without it.

2. Pin your SDK major version. mcp>=1.6.0 now resolves to the 2.x SDK, where FastMCP moved and 1.x-style code breaks at import time. My requirements now read mcp>=1.6.0,<2. If your MCP server mysteriously stopped working after a fresh install, this is probably why.

I verified the server end-to-end over stdio with the real SDK — tools list correctly, and create/search/list all round-trip.

The MCPB packaging gotcha

If you ship an .mcpb bundle: Anthropic's mcpb pack tooling and some registries disagree about the manifest. Smithery's registry requires inputSchema objects on each tool in the manifest; Anthropic's packer rejects that same key. I ended up maintaining two bundles — one Anthropic-packed (attached to the GitHub release) and one hand-packed for Smithery. Check your target registry's manifest rules before you package, not after.

If you want more than notes

The notes server is one of three starter servers in a paid pack I sell — the other two are a read-only SQLite lookup server (SELECT-only validation, tested against 15 attack patterns) and a web-summary resource/prompt skeleton — plus testing and security checklists:

MCP Server Starter Templates (Python): 3 Working Servers — $49 on my Gumroad store: https://bradray2.gumroad.com

The free one is genuinely free, no email gate. If you build something with it, I'd love to hear what.

Top comments (0)