notes-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notes-mcp-server save a note that we chose pgvector over qdrant because ops runs Postgres, tag architecture"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
notes-mcp-server
A Model Context Protocol server that gives an AI assistant a persistent, searchable notebook. Claude (or any MCP client) can save notes, find them with full-text search, update and tag them — stored locally in a single SQLite file.
You: remember that we chose pgvector over qdrant because ops already runs Postgres
Claude: [add_note] Saved as note #12, tagged "architecture".
You: why did we pick pgvector again?
Claude: [search_notes "pgvector"] → note #12: "...chose [pgvector] over qdrant because ops already runs Postgres"Built on the official Python SDK (mcp 2.x, MCPServer).
Tools
Tool | Annotation | Purpose |
| read-only | Full-text search over title, body and tags; best match first, matching words |
| read-only | Full text of one note |
| read-only | Tags in use with counts |
| write | Create a note |
| write | Change only the fields passed |
| destructive | Permanent delete — the server instructions tell the model to confirm with the user first |
Resources: notes://recent (ten latest notes) and notes://{id} (one note as markdown).
Every tool returns structured output with a JSON schema, so clients get typed fields rather than text to parse.
Related MCP server: NoteKeeper MCP
Design notes
Search is safe against FTS syntax in user input. SQLite FTS5 treats quotes, *, -, NOT and NEAR(...) as operators; passing a model's query straight into MATCH either throws or silently changes the meaning. Every word is quoted as a literal before matching. The test suite throws hostile strings at it to prove nothing raises.
Ranking favours titles. bm25() is weighted 10 : 1 : 5 for title : body : tags, and the Porter tokenizer matches building to builds. The FTS index is kept in sync with triggers on insert, update and delete.
Errors are useful to the model, not leaky. Expected failures (missing note, empty title, malformed tag) are raised as ToolError, so the model sees note 404 does not exist and can recover. Anything unexpected is left to the SDK, which reports a generic error without exposing internals.
Thread-safe store. The SDK runs synchronous tools in a worker-thread pool, while a default SQLite connection only works on the thread that opened it — the server would fail on its second call. The store opens the connection with check_same_thread=False and serialises access with a lock. This bug was invisible in unit tests of the store and only showed up when the tests went through a real MCP client, which is why most server tests do.
Input limits. Titles up to 200 characters, bodies up to 20,000, tags restricted to [a-z0-9_-], search results capped at 50.
Install
pip install git+https://github.com/HlebYakhnitski/notes-mcp-serverClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"notes": {
"command": "notes-mcp",
"env": { "NOTES_DB": "~/.notes-mcp/notes.db" }
}
}
}On Windows, if notes-mcp is not on PATH, use "command": "python", "args": ["-m", "notes_mcp.server"].
Any other client
The server speaks MCP over stdio: python -m notes_mcp.server. The database path comes from NOTES_DB (default ~/.notes-mcp/notes.db).
Development
pip install -e ".[dev]"
pytest31 tests. The storage layer is tested directly; the server is tested through the SDK's Client connected in-process, which exercises tool schemas, structured output, annotations, error reporting and resources exactly as a real client sees them. A concurrency test writes from eight threads at once.
License
MIT
Available Tools
6 toolsadd_noteC
Create a note. Tags are optional lowercase labels used for filtering.
Inputs: body (required), title (required), tags. Returns: id, body, tags, title, +2 more
delete_noteADestructiveIdempotent
Permanently delete a note. Confirm with the user first.
Inputs: note_id (required). Returns: deleted_id
get_noteBRead-only
Return the full text of one note.
Inputs: note_id (required). Returns: id, body, tags, title, +2 more
list_tagsARead-only
All tags in use, with how many notes carry each one.
Inputs: no named parameters. Returns: object
search_notesARead-only
Full-text search over titles, bodies and tags, best match first. Matching words are wrapped in [brackets] in the snippet. Optionally filter by one tag.
Inputs: query (required), tag, limit. Returns: result
update_noteA
Change a note. Only the fields you pass are updated; passing tags replaces all tags.
Inputs: note_id (required), body, tags, title. Returns: id, body, tags, title, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct resource-action pair: create, full-text search, retrieve, update, delete, and tag enumeration. The only near-neighbors (search_notes vs list_tags) are clearly separated by purpose (content matching vs tag inventory). No two tools appear interchangeable.
All names follow a strict snake_case verb_noun pattern (add_note, search_notes, get_note, update_note, delete_note, list_tags). The convention is predictable and the verbs accurately signal semantics (add vs get vs update vs delete).
Six tools is well-scoped for a notes server: full CRUD plus search and tag listing, with no filler or redundant variants. Every tool earns its place in a core workflow.
CRUD, full-text search with tag filtering, and tag inventory cover the essential note lifecycle with no dead ends for typical workflows. Minor gap: there is no plain list_notes for enumerating notes without a search term, and no tag rename/delete operation, though both are largely workable via search and update_note.
Related MCP Connectors
Create, search, and update notes in an xNotepad AI notebook, with semantic search and AI Q&A.
Save, search and edit your private notes by talking to your AI assistant.
AI access to your aNotepad online notes: read, search, write, and organize via 22 tools.
Notes and actions in one app. Let Claude or ChatGPT read and update them.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search, read, create, update, and remove personal markdown notes stored locally, providing persistent memory across sessions.16 npm2MIT
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with tools to create, list, search, tag, and delete notes stored in a local SQLite database.-
- AlicenseAqualityCmaintenanceEnables coding agents to persist notes, decisions, requirements, and learnings per project in SQLite and retrieve them across sessions via search and status tools.3MIT
- AlicenseAqualityBmaintenanceEnables AI agents to store, full-text search, and organize notes with tags.7MIT