md-reader-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., "@md-reader-mcp search my notes for 'budget' and list the results"
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.
md-reader-mcp
A Model Context Protocol server that gives an AI client (Claude Desktop, Claude Code, …) structured access to your Markdown notes on a NAS — read, search, write, tags, backlinks, and rendering — through the local API of the Markdown Reader & Editor desktop app.
The app is the hub: connections (SMB / SFTP / FTP / WebDAV, e.g. a ZimaOS box)
are configured there, passwords live in your OS keychain, and this server is a
thin bridge over the app's 127.0.0.1 API.
Setup
Markdown Reader ▸ Preferences ▸ Local API — turn it On. It shows a URL (
http://127.0.0.1:41100by default) and a bearer token.Add this server to your MCP client. For Claude Desktop (
claude_desktop_config.json):{ "mcpServers": { "md-reader": { "command": "npx", "args": ["-y", "md-reader-mcp"], "env": { "MDR_API_URL": "http://127.0.0.1:41100", "MDR_API_TOKEN": "paste-the-token-from-preferences" } } } }For Claude Code:
claude mcp add md-reader -e MDR_API_TOKEN=… -- npx -y md-reader-mcpKeep Markdown Reader running while you use the tools.
Related MCP server: second-brain-mcp
Tools
Tool | What it does |
| the servers configured in the app |
| add a NAS / server (name, protocol, host, credentials…) |
| manage a connection |
| the Markdown tree under a folder |
| content + front matter + tags (+ |
| create or overwrite a note |
| full-text search |
| notes that link to a given note |
| every |
| render arbitrary Markdown with the app's engine |
Notes
The API is
127.0.0.1-only and token-gated. This server never sees your passwords — only the token, which you can regenerate in Preferences.write_noteoverwrites. Run your MCP client so it confirms tool calls if you want a checkpoint before writes.
License
MIT © Vasyl Madei
Available Tools
11 toolsadd_connectionAdd a server connectionA
Add a NAS / server connection to Markdown Reader. The password is stored in the OS keychain by the app.
Inputs: host (required), name (required), protocol (required), port, +6 more.
backlinksBacklinksA
List the notes that link to a given note (Markdown links or [[wikilinks]]).
Inputs: path (required), connection (required).
list_connectionsList server connectionsA
List the NAS / server connections configured in Markdown Reader (no passwords).
Inputs: no named parameters.
list_notesList notesA
List the Markdown files (as a tree) under a folder on a connection.
Inputs: connection (required), path.
list_tagsList tagsB
Every #tag and front-matter tag across a connection, with counts and file lists.
Inputs: connection (required).
read_noteRead a noteA
Read a Markdown note. Returns its content, front matter, tags, and optionally HTML.
Inputs: path (required), connection (required), render.
remove_connectionRemove a server connectionA
Delete a connection (and its stored password) from Markdown Reader.
Inputs: id (required).
render_markdownRender MarkdownA
Render arbitrary Markdown to HTML using Markdown Reader’s engine (GitHub alerts, KaTeX, tags, task lists). Also returns front matter and tags.
Inputs: markdown (required).
search_notesSearch notesB
Full-text search across the Markdown files on a connection.
Inputs: query (required), connection (required).
test_connectionTest a server connectionB
Check that a configured connection can reach its server.
Inputs: id (required).
write_noteWrite a noteB
Create or overwrite a Markdown note with the given content.
Inputs: path (required), content (required), connection (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clear, distinct purposes. Minor overlap exists between read_note and render_markdown (both can return note content/HTML), but overall the query, write, and connection-management tools are clearly separated.
Names mostly follow a consistent verb_noun pattern (list_notes, read_note, write_note, add_connection). The exception is 'backlinks', which is a noun rather than a verb_noun, making it slightly inconsistent.
11 tools is well-scoped for a note-taking server with connection management. Each tool serves a distinct, practical function without unnecessary bloat.
Core note workflows (read, write, search, list, render, tags, backlinks) and connection lifecycle (add, remove, list, test) are covered. Missing explicit delete/rename note operations, though overwriting via write_note mitigates this gap.
Maintenance
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
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.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants like Claude and Codex to read, write, search, and traverse Markdown notes stored in a self-hosted knowledge base.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to capture, search, update, and delete notes in a local Markdown vault with automatic categorization and tagging, making knowledge management seamless.6 npm1MIT
- AlicenseAqualityBmaintenanceEnables AI clients to read Markdown notes from a single explicitly granted local folder, read-only, with strict containment against access outside that folder.1MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to read, create, update, delete, and search markdown notes stored locally.-