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., "@mcp-notes-server search my notes for pad thai recipe"
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.
An MCP server that gives an AI agent a searchable
markdown notes vault: six tools over a flat directory of .md files with YAML-style
frontmatter.
Notes stay plain markdown on disk. Nothing is locked in a database, so the same files
work with your editor, grep, and git.
~/notes/
├── pad-thai.md
├── sourdough-starter.md
└── weekly-review.mdTool | Description |
| Create a note. Returns the generated slug. |
| Read one note in full, by slug. |
| Summaries (no bodies), newest first, optionally filtered by tag. |
| Ranked full-text search with snippets. |
| Patch title / body / tags. The slug never changes. |
| Delete a note by slug. |
Related MCP server: Memory MCP Server
npm install
npm run buildAdd it to your client's server config — for Claude Desktop, claude_desktop_config.json:
{
"mcpServers": {
"notes": {
"command": "node",
"args": ["/absolute/path/to/mcp-notes-server/dist/src/index.js", "--vault", "/absolute/path/to/notes"]
}
}
}The vault directory is resolved in this order: --vault <dir>, then $NOTES_VAULT,
then ~/notes. It is created on startup if it does not exist.
Slugs are the identity, and they are validated. A note lives at <vault>/<slug>.md,
and every slug is checked against /^[a-z0-9]+(?:-[a-z0-9]+)*$/ before it reaches the
filesystem. That is what makes read_note({slug: "../../.ssh/id_rsa"}) impossible rather
than merely unlikely — an allowlist, not an escaping pass. Slugs are also stable across
updates: renaming the file when the title changes would invalidate any slug the model is
still holding from an earlier tool call.
Tool errors are data, not exceptions. "No note with slug X" comes back as a normal
tool result with isError: true, so the model reads it and corrects itself. If it were
thrown, the client would see a protocol error, which the model cannot recover from.
Genuine bugs (anything that is not a VaultError) are still thrown, so they stay loud.
Search is weighted term frequency. A term in the title counts triple and a term in a
tag counts double, so searching sourdough ranks a note about sourdough above one that
mentions it in passing. It is deliberately simple — no index to keep in sync, and a vault
of a few thousand notes scans in milliseconds.
The vault knows nothing about MCP. src/vault.ts is plain filesystem code, src/server.ts
is the MCP binding, and src/index.ts is the stdio entry point. That split is why the
vault can be tested directly and the server can be tested through a real MCP client over
an in-memory transport, with no subprocess and no mocks.
npm test # 46 tests, vitest
npm run typecheck # tsc --noEmit
npm run build # emit to dist/Tests cover the vault directly (test/vault.test.ts) and the server end to end through a
real MCP Client over InMemoryTransport (test/server.test.ts), so tool schemas,
argument validation, and result shapes are all exercised — not just the logic behind them.
MIT
Create a new markdown note. Returns the generated slug, which is the identifier every other tool takes. Slugs are derived from the title and de-duplicated automatically.
Inputs: body (required), title (required), tags.
Permanently delete a note by slug. This cannot be undone.
Inputs: slug (required).
List note summaries (no bodies), most recently updated first. Use this to get your bearings before reading or searching.
Inputs: tag, limit.
Read a single note in full, by slug.
Inputs: slug (required).
Full-text search over titles, tags, and bodies. Returns ranked hits with a snippet; matches in the title or tags outrank matches in the body.
Inputs: query (required), limit.
Replace the title, body, and/or tags of an existing note. Omitted fields are left untouched. The slug never changes.
Inputs: slug (required), body, tags, title.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool has a distinct purpose: create, read, list, search, update, and delete notes. No two tools overlap in functionality, and the descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern (create_note, read_note, list_notes, search_notes, update_note, delete_note), making the API predictable and easy to navigate.
With 6 tools covering the full CRUD lifecycle plus listing and search, the set is well-scoped for a notes server. No redundant or missing tools; each earns its place.
The tool surface provides complete coverage for note management: create, read, list, search, update, and delete. There are no obvious dead ends or missing operations for the intended domain.
Your Valutorio Markdown notes, readable and writable by your AI. Needs Valutorio Sync.
Markdown notes and whiteboards your AI agent can read and write.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
