notes-mcp

An MCP server for a personal notes / knowledge base. Create, search, and retrieve notes — and let an AI assistant (Claude Desktop, Claude Code, …) work with them directly.

The Model Context Protocol is an open standard that lets AI assistants securely call your tools and read your data. notes-mcp is a small, self-contained MCP server that turns a folder of notes into something an assistant can use in natural language — "save this as a note tagged billing", "what did I write about late check-out?", "summarize everything tagged onboarding".

It exercises all three MCP primitives:

Primitive	What this server exposes
Tools	create_note, update_note, delete_note, get_note, search_notes, list_tags
Resources	Every note at note://<id> — the client can pull note content straight into context
Prompts	summarize_tag — gathers all notes for a tag and asks the model to synthesize them

Tech

• TypeScript on Node 20+
• @modelcontextprotocol/sdk — the official MCP SDK (stdio transport)
• Zod — input schemas / validation
• Zero native dependencies — notes are stored in a plain JSON file, so there's nothing to compile. The storage layer is isolated in src/store.ts; swapping in SQLite later would touch only that file.
• node:test — the test suite spawns the built server and drives it over the real MCP protocol as a client would.

Install & build

pnpm install     # or npm install
pnpm build       # compiles src → dist
pnpm test        # spawns the server and exercises the MCP protocol end-to-end

Where notes are stored

A single JSON file at ~/.notes-mcp/notes.json by default. Override the location with the NOTES_MCP_DIR environment variable.

Connect it to an assistant

The server speaks MCP over stdio, so any MCP client can launch it.

Claude Desktop — add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/notes-mcp/dist/index.js"]
    }
  }
}

Claude Code — one command:

claude mcp add notes -- node /absolute/path/to/notes-mcp/dist/index.js

Then ask the assistant to create, search, or summarize notes — it will call the tools above. To point the store somewhere specific, add an env var to the config ("env": { "NOTES_MCP_DIR": "/path/to/notes" }).

Try it without a client

The MCP Inspector is the quickest way to poke at the tools by hand:

npx @modelcontextprotocol/inspector node dist/index.js

Scripts

Command	What it does
pnpm build	Compile TypeScript to dist/
pnpm watch	Recompile on change
pnpm start	Run the built server on stdio
pnpm test	Spawn the server and run the MCP round-trip
pnpm typecheck	Type-check without emitting

How it's structured

src/
  store.ts    # file-backed note store: CRUD + search (no MCP knowledge)
  index.ts    # MCP server: wires the store to tools, resources, and prompts
test/
  smoke.test.mjs  # connects a real MCP client to the spawned server

Keeping store.ts free of any MCP types means the storage layer is testable on its own and replaceable without touching the protocol wiring.

License

MIT