project-notes: an MCP server of your own

The complete code from the Code Craft Studio video "How to Build an MCP Server of Your Own". Video: (link goes here)

A personal MCP server over a folder of markdown notes. It exposes the three MCP primitives:

Quickstart (under 5 minutes)

Requires Python 3.10+ and uv.

git clone <this repo> && cd mcp-notes
uv sync

Test it with the MCP Inspector before touching any client:

npx @modelcontextprotocol/inspector uv run server.py

The Inspector lists both tools. Call search_notes with auth and you should see hits from auth-decision.md.

Related MCP server: Local Knowledge Desk

Wire it into Claude Code

# just you, this project (default: local scope)
claude mcp add notes -- uv run server.py

# every project you own
claude mcp add notes --scope user -- uv run server.py

# your whole team, via git
claude mcp add notes --scope project -- uv run server.py

Project scope writes .mcp.json (one is already included here). Commit it: teammates who clone this repo and open Claude Code get a one-time approval prompt, then they are connected too.

Check the connection inside Claude Code with /mcp, then ask: "What did we decide about auth?"

Go remote

Stdio runs on your machine with no port and no hosting. To serve a team from one box:

uv run server.py --http

That switches the transport to streamable HTTP. Once it is on a network, treat it as production: TLS in front, OAuth for authentication (both supported by the protocol), and read SECURITY-CHECKLIST.md first.

The gotcha to remember

On stdio, stdout is the protocol channel. One stray print() corrupts the JSON stream and the client reports "connection failed". This server logs to stderr; keep it that way.

Files

server.py               the whole server, ~90 lines
notes/                  sample notes (replace with your own)
.mcp.json               project-scope config, committed for the team
pyproject.toml          pinned dependency (see checklist item 3)
SECURITY-CHECKLIST.md   harden it from day one

License

MIT. Use it, fork it, ship it.