SoloMD MCP
A Rust MCP server for a folder of Markdown notes: an agent searches and reads notes and sees backlinks, tags, tasks and version history
- 1,336 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads the contents of every note in the connected folder, personal ones included, and hands it to the client in full
- With --allow-write it creates and replaces notes, rolls back their versions and exports files to other folders
- In HTTP mode it accepts network requests, and without a token anyone who can reach the address gets the notes
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/zhitongblog/solomd/main/scripts/install-mcp.sh | bashDownloads the right binary from the latest release to `/usr/local/bin/solomd-mcp`, or `~/.local/bin` when that is not writable. Works on macOS and Linux.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads the contents of every note in the connected folder, personal ones included, and hands it to the client in full
- With --allow-write it creates and replaces notes, rolls back their versions and exports files to other folders
- In HTTP mode it accepts network requests, and without a token anyone who can reach the address gets the notes
This is third-party code. Review the repository files before installing.
What it does
`solomd-mcp` is a standalone Rust program that turns a folder of Markdown notes into a tool for an agent. An MCP client starts it with the folder: `solomd-mcp --workspace /Users/me/Documents/Notes`, and exchange runs over stdio. The SoloMD desktop editor bundles a copy of this program but never runs it itself: the server starts only when a client asks. It also works without the editor, since plain files are enough. By default the server only reads. `list_notes` lists notes with a title, size and short summary, `read_note` returns the text, headings, tags and outbound `[[wikilinks]]`, and `search` looks for a substring or regular expression (through ripgrep when it is on `PATH`). The rest read structure: `get_backlinks`, `list_tags`, `get_outline` and `list_tasks` with `- [ ]` and `- [x]` checkboxes. A note's version history comes from `autogit_log` and `autogit_diff`. The `--allow-write` flag enables `write_note`, `append_to_note`, `autogit_rollback` and `export_note`. Several folders can be connected with `--workspace alias=path`, the first one being the default. For clients that cannot launch local programs there is a `--transport http` mode.
Who it is for. For people who keep notes, a journal or a knowledge base in Markdown and want Claude Code, Codex, Cursor or Continue to search, read and optionally extend them. The SoloMD editor is not required.
Good fit when
- You ask an agent to find every mention of a project or client in your notes, and `search` with a regular expression returns up to 200 hits with three lines of context
- You need a list of open tasks: `list_tasks` gathers every `- [ ]` box in the folder with its file and line, and the `done` filter keeps finished or unfinished ones
- An agent has to understand links between notes: `get_backlinks` shows which notes point to a chosen one, and `list_tags` counts tags across the folder
- You want to see how a note changed and undo a mistake: `autogit_diff` compares two versions, and `autogit_rollback` restores old content when writing is enabled
- Notes sit in several folders and each must be connected under its own name (`work=...`, `home=...`) through one server
Not a fit when
- Your notes live in a closed cloud service with no ordinary Markdown files: the server needs a folder on disk
- You need to edit an Obsidian vault with all its plugins and commands: this server sees only files and knows nothing about the app
- You need semantic search by meaning: `search` looks for a substring or regular expression, not vector similarity
- You need to export notes to HTML or DOCX on a normal install: `export_note` needs Node.js and the SoloMD sources, which the app does not ship
Example request
Find all unfinished tasks for the launch project in my notes, group them by file and show which notes they link toMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
SOLOMD_MCP_TOKENsecret- Token for HTTP mode, instead of the --auth-token parameter
SOLOMD_EXPORT_SCRIPT- Path to the solomd-export.mjs script for the export_note tool
SOLOMD_MCP_LOG- Log level, for example trace
Limitations
There are 16 tools in all, and `export_note` is listed only when `node` is on `PATH` and the `solomd-export.mjs` script is found (`SOLOMD_EXPORT_SCRIPT` sets the path, or it is looked up in a cloned repository). The installed app ships neither Node.js nor that script.
All paths are canonicalized and checked to lie inside the folder, and `..` and absolute paths outside are rejected. The exception is `export_note` with `--allow-write`: it writes outside the folder but creates no directories and does not replace a file without `overwrite: true`.
In HTTP mode the server listens on 127.0.0.1:8765. Without `--auth-token` or `SOLOMD_MCP_TOKEN` anyone who can reach the address gets the notes. `list_notes` returns 100 notes by default. License: MIT.
How to disable. In Claude Code run `claude mcp remove solomd-vault -s user`, in Codex delete the `[mcp_servers.solomd-vault]` section from `~/.codex/config.toml`. If the server was installed by script, delete the `solomd-mcp` file from `/usr/local/bin` or `~/.local/bin`. To forbid writing, remove `--allow-write` from the launch arguments and restart the client.
FAQ
How do I give Claude Code access to my Markdown notes?
Install `solomd-mcp` and run `claude mcp add --scope user solomd-vault -- solomd-mcp --workspace /path/to/notes`. For one project put an `.mcp.json` in its root with an `mcpServers` block where `command` is `solomd-mcp` and `args` hold `--workspace` and the path.
Can SoloMD MCP change my notes?
Not by default. The write tools (`write_note`, `append_to_note`, `autogit_rollback`, `export_note`) are shown to the client, but a call ends with a message to restart with `--allow-write`. `write_note` replaces an existing file only with the `allow_overwrite: true` argument.
Do I need the SoloMD editor to use SoloMD MCP?
No. `solomd-mcp` is a separate binary, and the editor only bundles a copy in the app package (on macOS `/Applications/SoloMD.app/Contents/MacOS/solomd-mcp`). The folder can be any folder with `.md` files.
How do I connect several note folders to one server?
Repeat the `--workspace` parameter with aliases, for example `--workspace work=/Users/me/Documents/Work --workspace home=/Users/me/Documents/Home`. The first folder is the default, and for another one a tool call passes a `workspace` argument with the alias or an absolute path.
How do I run SoloMD MCP over HTTP for cloud clients?
`solomd-mcp --workspace <folder> --transport http --bind 127.0.0.1:8765 --auth-token "$TOKEN"` enables Streamable HTTP. The address listens only on this computer until you change `--bind`, and the token arrives in the `Authorization: Bearer` header.
How do I register SoloMD MCP in all clients automatically?
`solomd mcp install` from the `solomd` CLI writes the server into every AI client it finds, and `solomd mcp-config` only prints the configuration. The CLI installs with the repository's `scripts/install-cli.sh` script.
Discussion
No questions or reviews yet.
Related
MCP serversObsidian MCP
obsidian-mcp
A local MCP server for Obsidian vaults: reads and edits explicitly configured folders of Markdown files, Obsidian need not be open
Minutes
minutes
A local-first MCP server for meeting memory: on-device recording and transcription into Markdown, searchable from Claude Code, Codex, Cursor and any MCP client
Obsidian MCP Server
obsidian-mcp-server
An MCP server for an Obsidian vault: read, search and precisely edit notes, sections, frontmatter and tags
A local MCP server for safe read, search and edit of notes in an Obsidian vault, restricted to the vault root
An MCP server for an Obsidian vault via the Local REST API plugin: search, read, append and patch notes
Trello MCP server with 57 tools: cards, lists, checklists, attachments, comments, custom fields and workspaces, plus acceptance-criteria extraction
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| SoloMD MCP (this entry) | yes | not required | 1,336 | |
| Obsidian MCP | no | not required | 742 | reads and edits Obsidian vaults in explicitly configured folders, while SoloMD MCP works with any Markdown folder and only reads by default |
| QMD | no | not required | 30,530 | local search over notes, docs and transcripts: keywords, semantic search and reranking |
README in short
The `mcp-server` folder holds the Rust sources, an MCPB package manifest and a detailed server description. It runs from launch and a table of 16 tools through three install methods, setup for Claude Code, Codex, Cursor and cloud clients, a parameter reference, safety rules and a handshake check. Nearby the repository holds a Tauri desktop editor with README translations into fourteen languages, a web clipper and install scripts.