AI Notes MCP Server

An MCP server that gives AI assistants like Claude a personal knowledge base. Ask the AI to save what you learn, find it again later, summarize a topic, or quiz you on it.

You: "Save a note: list comprehensions build a list in one line, like [x*x for x in range(10)]. Tag it python." AI: calls add_note → "Saved note Python list comprehensions."

You: "Quiz me on everything I noted about Python." AI: uses the study_quiz prompt → asks you 5 questions built from your own notes.

What is MCP?

The Model Context Protocol is an open standard that connects AI applications to external tools and data. Instead of building a custom integration for every AI app, you build one MCP server, and any MCP-compatible client (Claude Desktop, IDEs, agents) can use it.

flowchart LR
    U[You] -->|chat| C[AI app<br/>e.g. Claude Desktop]
    C <-->|MCP over stdio<br/>JSON-RPC| S[AI Notes MCP Server]
    S <-->|read / write| F[(notes.json)]

Related MCP server: om

Features

This server uses all three MCP building blocks:

🛠 Tools — actions the AI can take

📄 Resources — data the AI can read

💬 Prompts — ready-made tasks for the user

Quick start

Requirements: Node.js 18 or newer.

git clone https://github.com/YOUR_USERNAME/ai-notes-mcp-server.git
cd ai-notes-mcp-server
npm install
npm run build

Try it without any AI app — this starts the server and calls its tools like a real client would:

npm run demo

Use it with Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config.

2. Add the server to claude_desktop_config.json (use the full path to your folder):

Windows

{
  "mcpServers": {
    "ai-notes": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_NAME\\ai-notes-mcp-server\\dist\\index.js"]
    }
  }
}

macOS / Linux

{
  "mcpServers": {
    "ai-notes": {
      "command": "node",
      "args": ["/Users/YOUR_NAME/ai-notes-mcp-server/dist/index.js"]
    }
  }
}

3. Restart Claude Desktop. The tools appear in the tools menu of the chat.

Notes are saved in ~/.ai-notes-mcp/notes.json. To use another file, set the NOTES_FILE environment variable:

"ai-notes": {
  "command": "node",
  "args": ["/path/to/ai-notes-mcp-server/dist/index.js"],
  "env": { "NOTES_FILE": "/path/to/my-notes.json" }
}

Project structure

src/
├── index.ts    # Entry point: loads the notes file, starts the stdio transport
├── server.ts   # Registers the MCP tools, resources and prompts
└── store.ts    # NoteStore: storage, search ranking, atomic JSON persistence
tests/
├── store.test.ts   # Unit tests for storage and search
└── server.test.ts  # Integration tests: a real MCP client talks to the server
scripts/
└── demo.ts     # Starts the built server as a process and calls it over stdio

Design decisions

• Separation of concerns: NoteStore knows nothing about MCP, and server.ts knows nothing about files. The storage can be swapped (for example for SQLite) without touching the MCP layer.

• Input validation with Zod: every tool has a schema, so invalid input (an empty title, too many tags) is rejected before it reaches the code, and the AI sees exactly which parameters exist.

• Safe writes: changes are written to a temporary file and then renamed, which is atomic — a crash can't leave a half-written notes.json.

• Logging to stderr: with the stdio transport, stdout carries the protocol messages, so anything printed there would break the connection.

• Tool annotations: read-only tools are marked readOnlyHint and delete_note is marked destructiveHint, so clients can decide when to ask the user for permission.

Testing

npm test          # 15 unit + integration tests
npm run typecheck # strict TypeScript check

The integration tests connect a real MCP Client to the server over an in-memory transport, so they test the server exactly the way an AI app uses it. GitHub Actions runs everything on Node 20 and 22 for every push.

Ideas for next steps

• Semantic search with embeddings, so "car" also finds notes about "vehicles"

• SQLite storage for large knowledge bases

• Streamable HTTP transport to run the server remotely

• Import notes from Markdown files or an Obsidian vault

Tech stack

TypeScript (strict) · Node.js · MCP TypeScript SDK · Zod · node:test · GitHub Actions

License

MIT © Ibrahim Belkahla