io.github.bradraylucas-eng/mcp-notes-server

mcp-notes-server

A minimal, free and open-source Model Context Protocol (MCP) server in Python that gives any MCP-compatible AI assistant a persistent notebook: create notes, list them, and search them — stored in a plain local JSON file you own.

Built with the official mcp Python SDK (FastMCP). No database, no cloud, no accounts. Your notes never leave your machine.

Tools

Quick start

git clone <this-repo-url>
cd mcp-notes-server
pip install -r requirements.txt
python server.py

The server speaks MCP over stdio. Connect it from any MCP host — see the config examples below and in examples/.

Claude Desktop

Add to your claude_desktop_config.json (see examples/claude_desktop_config.example.json):

{
  "mcpServers": {
    "notes-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-notes-server/server.py"]
    }
  }
}

Generic MCP host

See examples/mcp-client-config.generic.json — the same stdio command/args pattern works for most hosts.

Try it

1. Connect your MCP host and ask: "Create a note titled 'Shopping list' with milk, eggs, and coffee."
2. Ask: "Search my notes for eggs."
3. Open notes.json (created automatically next to server.py) to see the raw storage — it's just JSON.

How it works

• Storage helpers load/save a single notes.json file; saves are atomic (write to temp file, then replace).
• Every tool validates its input (title required and length-capped, body length-capped, search query required).
• Tool functions are ordinary Python functions decorated with @mcp.tool() — the type annotations become the tool input schemas. The whole server is one readable file (~150 lines), meant to be copied and adapted.

Run the smoke test (no MCP host needed):

python tests/smoke_test.py

Verified end-to-end over the real MCP protocol (stdio, official SDK v1.x) — tools listed, note created, searched, and listed: see tests/mcp_e2e_test.py and run it yourself after pip install -r requirements.txt. Note the requirements pin mcp<2: the 2.x SDK renamed FastMCP, and this code targets the v1 API.

Scope & safety

• Local only. This server reads/writes one JSON file in its own folder. It makes no network calls and has no delete tool — by design, as a starter pattern.
• Treat it as a learning/prototyping base, not a hardened production service: no authentication (stdio servers are launched by your host as your user), no concurrency locking beyond atomic file replacement.

Get the full pack

This free server is one of three starters in the MCP Server Starter Templates pack — the full pack adds a read-only SQLite lookup server (with a tested SQL-injection guard: SELECT-only validation) and a web-summary server skeleton, plus client configs for all three, a testing checklist, and security notes for taking MCP servers toward production.

→ MCP Server Starter Templates (and more AI agent tools: AgentProof testing kits, LLM/RAG eval kits, verified datasets for agents): bradray2.gumroad.com

Free samples of the paid kits live in the companion repo, ai-agent-tools-free-samples.

License

MIT — see LICENSE. Use it, fork it, ship it.

Copyright (c) 2026 Brad Lucas.