Provides tools for reading and optionally editing Markdown files, including reading whole files or specific heading sections, listing section structure, and when writable, overwriting, appending, deleting sections, and setting front matter.
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., "@markdown-mcp List the sections in README.md"
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.
Markdown MCP is a small, dependency-free MCP server for reading and optionally editing existing Markdown files beneath one configured root folder. It is offline-first, uses newline-delimited JSON-RPC over stdio, and is suitable for LM Studio and other MCP hosts.
Version: 0.1.0. Python 3.10 or newer is required.
No installation or runtime download is needed:
python /path/to/markdown-mcp/server.py /path/to/markdown/rootThe default is read-only. Add --writable to publish editing tools:
python /path/to/markdown-mcp/server.py /path/to/markdown/root --writableThe root is required and must already be a folder. There is no configuration file, account, network access, telemetry, file creation, file deletion, or directory-listing tool.
Related MCP server: md-vision
The application has no runtime dependencies. Its build backend is pinned to
setuptools==80.9.0. For an offline installation, download that wheel on a
connected machine and copy the wheelhouse with the repository. Run these
commands from the repository root:
python -m pip download setuptools==80.9.0 -d wheelhouse
python -m pip install --no-index --find-links wheelhouse .Then run markdown-mcp ROOT [--writable].
Read-only example:
{
"mcpServers": {
"markdown": {
"command": "python",
"args": [
"/absolute/path/to/markdown-mcp/server.py",
"/absolute/path/to/markdown/root"
]
}
}
}Add "--writable" to the args array to enable edits. On Windows, JSON paths
may use forward slashes or escaped backslashes.
The local Tkinter helper generates copyable configuration with absolute paths. Launch it from macOS or Linux with:
/path/to/markdown-mcp/scripts/generate_mcp_config.shOn Windows, use:
C:\path\to\markdown-mcp\scripts\generate_mcp_config.cmdChoose the existing Markdown root and leave editing disabled for read-only
access, or enable it to add --writable. The helper shows a complete LM Studio
mcp.json object and a Codex [mcp_servers.markdown] config.toml entry. Copy
and merge the applicable snippet into the host configuration. The helper never
writes or merges host configuration files.
Read-only mode exposes:
read_markdown({"path": "guide.md#installation"}) reads a whole file, one
exact heading section, or leading front matter through #--- or #===.
list_sections({"path": "guide.md", "max_level": 3}) returns
has_front_matter and a flat source-ordered list of heading levels, titles,
and anchors. max_level defaults to 3 and accepts 1 through 6.
Writable mode additionally exposes:
overwrite_section preserves the selected heading and replaces its body and
descendants.
append_section appends a level-1 section to a file or exactly one level
below a selected parent.
set_front_matter adds, replaces, deletes, or idempotently leaves absent
leading front matter.
delete_section deletes a selected heading, body, and descendants.
Mutation tools operate only on existing files. A tool omitted in read-only mode is also rejected if called directly.
Paths may be root-relative or absolute. Absolute paths are only a convenience:
the resolved existing regular file must remain beneath the configured root.
Hidden and dot-prefixed folders are accessible when explicitly addressed.
Only .md and .markdown suffixes are accepted, without regard to suffix case.
Traversal and symbolic-link or junction escapes are rejected.
Only the final #fragment after a supported Markdown suffix is a selector, so
filenames such as draft#notes.md remain valid. Fragments are percent-decoded
once as strict UTF-8. Whitespace, controls, /, \, #, malformed escapes,
and empty fragments are rejected.
The parser recognizes level 1–6 ATX headings and level 1–2 Setext headings. Heading-like text in leading front matter, fenced code, or indented code is ignored. A section includes its heading, body, and descendants and stops before the next heading at the same or a higher level.
Anchors approximate GitHub heading anchors without a Markdown dependency:
visible link text replaces inline links, HTML tags and backticks are removed,
HTML entities and backslash escapes are decoded, whitespace collapses, text is
lowercased, spaces become -, Unicode is retained, punctuation except - and
_ is removed, and duplicate anchors receive -1, -2, and later suffixes.
Leading front matter must start on the first logical line after an optional
UTF-8 BOM. The exact opener must be --- or ===, and the closer must exactly
match it. Both selector aliases read either valid form. Malformed leading front
matter is never reinterpreted by a front-matter edit.
Every source is decoded completely as strict UTF-8 before use. A leading UTF-8 BOM is omitted from logical tool text and preserved by edits. Unaffected source text, newline style, final-newline behavior, and file mode are preserved. Writes use a flushed and fsynced same-directory temporary file, repeat path and source validation, then atomically replace the original. Failed writes remove their temporary files.
Source files, edited files, and semantic tool results have a hard 256 KiB UTF-8 limit. Paths are limited to 4,096 characters and generated heading titles to 1,000 characters through MCP. NUL-containing paths or documents and invalid UTF-8 are rejected with bounded errors.
Compact UTF-8 catalog measurements for 0.1.0 are 923 bytes for read-only mode and 2,092 bytes for writable mode.
From the repository root:
python -m unittest discover -s tests -vThe suite covers parser and mutation behavior, path confinement, source and result limits, atomic revalidation and cleanup, catalog filtering, LM Studio-compatible framing, and strict UTF-8 stdio under an inherited ASCII encoding.
List Markdown headings and generated anchors in source order.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| max_level | No |
| Name | Required | Description |
|---|---|---|
| sections | Yes | |
| has_front_matter | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses output ordering and that anchors are generated, but says nothing about read-only safety, error behavior for a missing path, or whether anchors reflect existing vs. synthesized targets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the key qualifiers (source order, generated anchors) front-loaded. No filler and nothing to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, but the definition still leaves the two input parameters unexplained and gives no usage context relative to read_markdown. Adequate but with clear gaps for a tool whose entire configuration surface is undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across two parameters. The description never mentions what 'path' points at or that 'max_level' caps heading depth (default 3, max 6), leaving the depth-limiting behavior completely undocumented in both schema and prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (List) plus a clearly bounded resource (Markdown headings and generated anchors), with the ordering stated. It implicitly separates itself from read_markdown by returning a structural outline rather than content, but never names or contrasts the sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this instead of read_markdown, no prerequisites, and no exclusions. The agent must infer the routing decision entirely from the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a validated Markdown file or exact #section/#--- block.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It hints that the file is "validated" (implying failure behavior for invalid Markdown) but says nothing about permissions, error conditions, or what happens when a requested section doesn't exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the resource and scope front-loaded and no wasted words. It is efficient, though the extreme brevity edges toward under-specification rather than pure conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and an undocumented parameter, the description should do more. The undefined "#---" block syntax and "validated" behavior leave an agent unable to predict what the tool returns or how it fails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the single path parameter, so the description must compensate. It adds meaningful semantics by indicating the path can address a whole file or a specific #section/#--- block, but the exact syntax and whether the fragment is part of the same path string is left unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Read) and resource (Markdown file), plus scopes to exact #section/#--- blocks, which distinguishes it from the sibling list_sections (which enumerates rather than reads). However, the cryptic "#---" notation and the meaning of "validated" are never explained, so some ambiguity remains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance and no mention of the alternative list_sections. The only implicit signal is that reading differs from listing, which the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_sectionsread_markdownScored across 2 tools
read_markdown returns Markdown content, while list_sections returns heading structure and anchors. Their purposes are clearly distinct with no overlapping behavior, so an agent can easily select the correct tool.
Both tools use a consistent snake_case verb_noun pattern: read_markdown and list_sections. There are no naming style deviations.
Two tools is borderline thin for a general Markdown MCP server, even if they are well-scoped for basic reading and navigation. The set feels minimal rather than comfortably complete.
The surface covers reading a file, reading a section/block, and listing sections, which is reasonable for read-only navigation. However, it lacks common lifecycle operations such as creating, updating, or searching Markdown content, so notable gaps remain for a broader Markdown server.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Create, validate, edit, export (markdown/svg/png/mermaid), and search JSON Canvas files.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Portable AI memory shared across models and harnesses - plain markdown you own.
