notes-mcp
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 find my notes about machine learning"
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
An MCP server that exposes your local Markdown notes to AI assistants. Supports keyword search across all .md files in a directory.
Tools
search_notes
Searches all notes using term-frequency scoring and returns ranked results with snippets.
Parameter | Type | Default | Description |
| string | required | Search terms (space-separated) |
| integer (1–20) |
| Maximum number of results to return |
Related MCP server: ai-lab
Setup
1. Install dependencies
npm install2. Build
npm run build3. Configure
Set the NOTES_DIR environment variable to the directory containing your .md files:
export NOTES_DIR=/path/to/your/notes4. Add to your MCP client
In Claude Code (~/.claude/claude_desktop_config.json or similar):
{
"mcpServers": {
"notes": {
"command": "node",
"args": ["/path/to/notes-mcp/build/index.js"],
"env": {
"NOTES_DIR": "/path/to/your/notes"
}
}
}
}Requirements
Node.js 18+
Markdown notes in a flat directory (subdirectories are not searched)
Available Tools
2 toolsread_noteRead NoteB
Return the full contents of a note by filename
Inputs: name (required).
search_notesSearch NotesA
Keyword-search all notes. Returns ranked filenames with snippets.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: read_note retrieves full content by exact filename, while search_notes performs keyword searches and returns ranked results. No overlap.
Both tools follow a consistent verb_noun pattern using snake_case (read_note, search_notes), making the naming predictable and clear.
With only two tools, the server feels minimal. While it could be acceptable for a read-only archive, typical note management servers benefit from additional tools for creation, deletion, or listing.
The tool surface is missing essential operations for managing notes, such as create, update, delete, or list all notes. An agent cannot perform full note lifecycle tasks, leading to likely failures.
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Personal context for every AI: search, read, and write back to your private Markdown library.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to search local Markdown documents using natural language, with automatic indexing and section-level retrieval.101MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to search and retrieve from a local knowledge base of markdown notes using hybrid semantic+keyword search, keeping data entirely offline.MIT
- AlicenseAqualityDmaintenanceEnables coding agents to search local notes via BM25 keyword ranking, returning relevant passages with file paths and line numbers, fully offline with zero dependencies.3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search, read, and navigate a folder of Markdown notes as a knowledge base, with full-text search, backlinks, tags, metadata, and note resources for conversation attachment.1MIT