A
licenseA
qualityC
maintenanceEnables AI agents to search local Markdown documents using natural language, with automatic indexing and section-level retrieval.
9
5
1
MIT
notes-mcp
Click on "Install 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-mcpfind 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: mcp-recall-md
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
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Note filename, e.g. 'invoices' |
TDQS
B3.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'full contents' but does not disclose potential error cases (e.g., file not found), return format, or any side effects. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence. It is front-loaded and not verbose, though it could benefit from a slight expansion (e.g., example filename).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is minimally adequate. However, missing details like error behavior and output format leave room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the parameter as 'Note filename, e.g. 'invoices''. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return'), resource ('note'), and parameter ('by filename'). It distinguishes from sibling 'search_notes' which is for searching, not reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a filename, but provides no explicit guidance on when to use this tool versus alternatives like 'search_notes', or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_notesSearch NotesA
Keyword-search all notes. Returns ranked filenames with snippets.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| query | Yes | Search terms |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description minimally discloses behavior: search across all notes and return ranked results. No mention of scope (e.g., user context), pagination, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence, front-loaded with key information. Slightly more detail could be added without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with 2 parameters and no output schema, the description adequately conveys purpose and output format. Missing details about ranking criteria.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 applies. The description adds no extra context about how parameters work (e.g., query syntax), merely repeating schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Keyword-search all notes') and states the output ('ranked filenames with snippets'), clearly distinguishing it from sibling tool 'read_note'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over 'read_note' or when not to use it. The description only implies usage for keyword-based search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
2 tool updates
v1.0.0- First observed
read_note - First observed
search_notes
TDQS
A3.6/5.0
Disambiguation5/5
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.
Naming Consistency5/5
Both tools follow a consistent verb_noun pattern using snake_case (read_note, search_notes), making the naming predictable and clear.
Tool Count3/5
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.
Completeness2/5
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
ActivityStale
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables semantic search over local markdown note collections using vector embeddings, with real-time file watching and zero-config setup.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants like Claude and Codex to read, write, search, and traverse Markdown notes stored in a self-hosted knowledge base.4MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search, read, create, update, and remove personal markdown notes stored locally, providing persistent memory across sessions.952MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ashleykarhoff/notes-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server