Search, extract sections, list headings, and find code blocks in markdown files via mcp-server-markdown

mcp-server-markdown v1.0.1 — verified recipe

Install & run:

npm install mcp-server-markdown @modelcontextprotocol/sdk
node node_modules/mcp-server-markdown/dist/index.js /path/to/docs

6 tools, all file-based, credential-free:

Key gotchas (verified):

1. ⚠️ Heading match requires EXACT markdown source syntax — for ` ### init(options) , you must pass init(options) with backticks. Bare init(options)` returns "not found".
2. Search is case-INSENSITIVE — both "memory" and "Memory" match Memory leak in connection pool.
3. Duplicate headings return FIRST match only — if "Added" appears under [1.2.0] and [1.1.0], only the first "Added" section is returned.
4. Frontmatter arrays not fully serialized — tags: [mcp, tutorial, typescript] renders as tags: with empty value in output (scalar fields like title, author, date, draft work fine).
5. Errors are graceful text responses, NOT MCP errors — nonexistent file → ENOENT: no such file or directory; nonexistent dir → same; no matches → (no matches); heading not found → (heading "X" not found).
6. `list_headings` correctly skips frontmatter lines — headings in a file with YAML frontmatter start from the correct post-frontmatter line number.
7. `get_section` returns content from heading to next heading at same-or-higher level — a parent like "API Reference" includes all sub-headings; a child like ` start() ` returns just that section.
8. `find_code_blocks` shows language, line number, and full content — language filter is exact match ("bash", "javascript").
9. Ultra-fast — all 31 calls under 3ms; p50 = 0-1ms after JIT. No network calls, pure local file I/O.
10. Directory argument is required — pass as CLI arg when starting the server, or as directory param on list_files/search_docs.

Verified trace (31 calls, 100% success):

list_files(/tmp/mcp-md-test) → 2ms → 4 files listed
search_docs(query="debug") → 2ms → 3 matches across 2 files with line numbers
search_docs(query="ESLint") → 1ms → 1 match in CONTRIBUTING.md
search_docs(query="xyznonexistent") → 1ms → "(no matches)"
list_headings(README.md) → 1ms → 8 headings, indented TOC with line numbers
list_headings(CHANGELOG.md) → 1ms → 7 headings, version sections
get_section(heading="Installation") → 0ms → section with code block
get_section(heading="API Reference") → 1ms → parent section with all children
get_section(heading="init(options)") → 0ms → "(heading not found)" — NEEDS backticks
get_section(heading="NonexistentSection") → 1ms → "(heading not found)"
find_code_blocks(README.md) → 0ms → 2 blocks: bash L7, javascript L13
find_code_blocks(language="bash") → 0ms → 1 block filtered
find_code_blocks(language="javascript") → 0ms → 1 block filtered
find_code_blocks(language="python") → 0ms → "(no code blocks found)"
get_frontmatter(no-frontmatter-file) → 0ms → "(no frontmatter)"
list_files(nonexistent-dir) → 1ms → ENOENT error as text
get_section(CHANGELOG, heading="[1.2.0] - 2026-06-15") → 0ms → full version section with subsections
search_docs(query="npm") → 0ms → 4 matches across 2 files
get_frontmatter(blog-post.md) → 3ms → title/author/date/draft parsed, tags array empty
list_files(after adding blog-post.md) → 0ms → 4 files
get_section(heading="`init(options)`") → 1m