English Français العربية

io.github.ofershap/markdown

Official registry Developer tools

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

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package mcp-server-markdown
Claude Code 
claude mcp add markdown -- npx -y mcp-server-markdown@1.0.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "markdown": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-server-markdown@1.0.1"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. mcp-server-markdown
  2. Why
  3. Tools
  4. Quick Start
  5. Examples
  6. Agent Plugins
  7. FAQ
  8. Development
  9. See also
  10. Author
  11. License

mcp-server-markdown

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

npx mcp-server-markdown

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

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:

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

Add to claude_desktop_config.json:

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

Add to user settings or .vscode/mcp.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

git clone https://github.com/ofershap/mcp-server-markdown.git
cd mcp-server-markdown
npm install
npm test
npm run build

See also

More MCP servers and developer tools on my portfolio.

Author

README built with README Builder

License

MIT © 2026 Ofer Shapira

Frequently asked questions

What is io.github.ofershap/markdown?

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

How do I install io.github.ofershap/markdown?

It runs on your machine. In Claude Code: claude mcp add markdown -- npx -y mcp-server-markdown@1.0.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.ofershap/markdown need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.ofershap/markdown open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.ofershap/markdown?

It is published by ofershap. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.