Skip to main content
Glama

AI Notes MCP Server

CI TypeScript MCP License: MIT

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: AI Sticky Notes

Features

This server uses all three MCP building blocks:

๐Ÿ›  Tools โ€” actions the AI can take

Tool

What it does

add_note

Save a note with a title, Markdown content and tags

search_notes

Keyword search, ranked by relevance (title โ€บ tags โ€บ content)

get_note

Read one note in full

list_notes

List notes, newest first, optionally filtered by tag

update_note

Change title, content or tags of a note

delete_note

Delete a note (marked as destructive, so clients ask for confirmation)

knowledge_stats

Number of notes, words, tags and last activity

๐Ÿ“„ Resources โ€” data the AI can read

URI

Content

notes://note/{id}

Every note as a Markdown document

notes://tags

All tags with their note counts (JSON)

๐Ÿ’ฌ Prompts โ€” ready-made tasks for the user

Prompt

What it does

summarize_notes

Summarizes all notes (or one tag), highlights key points and open questions

study_quiz

Creates quiz questions from your notes about a topic

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"]
    }
  }
}
  1. 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

Available Tools

7 tools
add_noteAdd noteB

Save a new note to the user's knowledge base. Use tags to group notes by topic (for example 'python', 'exam', 'ideas').

Inputs: title (required), content (required), tags.

delete_noteDelete noteA
Destructive

Permanently delete a note. Ask the user for confirmation before calling this.

Inputs: id (required).

get_noteGet noteA
Read-only

Read the full content of one note by its id.

Inputs: id (required).

knowledge_statsKnowledge base statisticsA
Read-only

Overview of the knowledge base: number of notes, tags and most recent activity.

Inputs: no named parameters.

list_notesList notesA
Read-only

List notes, newest first. Optionally only notes with a given tag.

Inputs: tag.

search_notesSearch notesA
Read-only

Find notes by keywords. Results are ranked by relevance (matches in the title count most, then tags, then content).

Inputs: query (required), limit.

update_noteUpdate noteA

Change the title, content or tags of an existing note. Only the fields you pass are changed.

Inputs: id (required), tags, title, content.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: add/get/update/delete a single note, list notes, search notes, and show aggregate stats. The boundary between list_notes and search_notes is resolved by descriptions (newest-first listing with optional tag filter vs keyword relevance search). No two tools appear to do the same thing.

    Naming Consistency4/5

    Six of seven tools follow a predictable verb_noun pattern (get_note, list_notes, update_note, delete_note, add_note, search_notes). knowledge_stats is a noun_phrase deviation, but it is still readable and clearly scoped.

    Tool Count5/5

    Seven tools is well-scoped for a notes/knowledge-base server. The set covers core operations plus search and stats without redundant or filler tools.

    Completeness5/5

    The surface provides full CRUD lifecycle coverage: add, read (get/list/search), update, and delete notes. Tag filtering, keyword search, and aggregate stats round out the expected workflows with no obvious dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A simple notes system that allows creating, storing, and accessing text notes through MCP resources and tools, with built-in prompt support for generating summaries of stored notes.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables managing plain-text notes on disk through MCP resources, tools, and prompts, so natural-language requests can create, read, search, delete, and summarize notes via an interactive client.
      MIT