Markdown

io.github.ofershapPublished by GitHub account ofershapv1.0.1Updated Oct 27, 2026

Markdown MCP — search, extract sections, list headings, find code blocks.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Local MCP server that lets an assistant search and navigate markdown files on disk by headings, sections, code blocks and frontmatter.

What you can do
  • List all .md files in a directory recursively
  • Full-text search across markdown files, case-insensitive, up to 50 results
  • Extract a section by heading and list headings as a table of contents
  • Find fenced code blocks, optionally filtered by language
  • Parse YAML frontmatter metadata at the start of a file
When to use it
Useful when your project wikis, ADRs, onboarding guides or internal docs live as markdown files in a repo or on disk and you want the assistant to search and pull out structured parts rather than raw text. It is a structured alternative to a plain filesystem server for documentation work.
Requirements
Runs locally over stdio, typically started with npx mcp-server-markdown, so Node.js and npm are needed. No API keys or authentication; the assistant passes directory and file paths to the tools. Desktop MCP clients such as Claude Desktop, Cursor or VS Code Copilot.
Before you install
It reads local markdown files from paths the assistant supplies, so point it only at directories you are comfortable exposing to the client. It is read-only per the listed tools; no credentials are requested.

Installation

In SourceWeft

  1. Open Markdown in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-server-markdown

[npm version] [npm downloads] [CI] [TypeScript] [License: MIT] [Agent Plugins]

Search, navigate, and extract content from local markdown files. Full-text search, section extraction, heading navigation, code block discovery, and frontmatter parsing.

bash
npx mcp-server-markdown

Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Reads local .md files, no auth needed.

[Install in Cursor]   [Add to VS Code]

[MCP server for searching and navigating markdown documentation]

Demo built with remotion-readme-kit

Why

Tools like Context7 are great for looking up library docs from npm, but they don't help with your own documentation. Project wikis, internal knowledge bases, architecture decision records, onboarding guides: they all live as markdown files in your repo or on disk. The filesystem MCP server can read those files, but it treats them as raw text. It doesn't understand headings, sections, or code blocks. This server does. Point it at a directory and your assistant can search across all your docs, pull out a specific section by heading, list the table of contents, or find every TypeScript code example in your knowledge base.

Tools

ToolWhat it does
list_filesList all .md files in a directory recursively (sorted alphabetically)
search_docsFull-text search across all .md files (case-insensitive, up to 50 results)
get_sectionExtract a section by heading until the next heading of same/higher level
list_headingsList all headings as a table of contents
find_code_blocksFind fenced code blocks, optionally filter by language (e.g. typescript)
get_frontmatterParse YAML frontmatter metadata at the start of a file

Quick Start

Cursor

Add to .cursor/mcp.json:

json
{  "mcpServers": {    "markdown": {      "command": "npx",      "args": ["-y", "mcp-server-markdown"]    }  }}

Claude Desktop

Add to claude_desktop_config.json:

json
{  "mcpServers": {    "markdown": {      "command": "npx",      "args": ["-y", "mcp-server-markdown"]    }  }}

VS Code

Add to user settings or .vscode/mcp.json:

json
{  "mcp": {    "servers": {      "markdown": {        "command": "npx",        "args": ["-y", "mcp-server-markdown"]      }    }  }}

Examples

  • "Search all docs in ./docs for mentions of 'authentication'"
  • "Show me the 'API Reference' section from README.md"
  • "List all headings in CONTRIBUTING.md"
  • "Find all TypeScript code blocks in the docs"
  • "What's the frontmatter metadata in this file?"
  • "Give me the table of contents for our architecture docs"

Agent Plugins

This repo is an Agent Plugins 1.0.0 package: plugin.json, portable mcp.json, and skills/ ship together with the MCP server.

For Cursor, clone the repo and copy or symlink it to ~/.cursor/plugins/local/mcp-server-markdown, then reload the window. Skills and MCP show up under Customize > Plugins.

The Cursor and VS Code install buttons above still work: they add the same npx -y mcp-server-markdown stdio server as manual JSON.

FAQ

What is mcp-server-markdown?

An MCP server that searches and navigates local .md files: full-text search, sections by heading, TOC, code blocks, and YAML frontmatter.

How is this different from Context7?

Context7 pulls published library docs from npm. This server indexes markdown already on your disk (wikis, ADRs, internal guides).

How is this different from the filesystem MCP?

Filesystem tools read raw files. This server understands headings, sections, fenced code, and frontmatter.

Can I install it as an Agent Plugin in Cursor?

Yes. Use ~/.cursor/plugins/local/mcp-server-markdown so the bundled markdown-search skill loads with the MCP config.

Do I need API keys?

No. Paths are local; the agent passes directory and file paths to the tools.

Development

bash
git clone https://github.com/ofershap/mcp-server-markdown.gitcd mcp-server-markdownnpm installnpm testnpm run build

See also

More MCP servers and developer tools on my portfolio.

Author

[Made by ofershap]

[LinkedIn] [GitHub]

README built with README Builder

License

MIT © 2026 Ofer Shapira

Source: README.md at commit f845545

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts