Enables AI clients to search, navigate, and extract structured content from local markdown files including headings, sections, and code blocks.
Also known as ofershap/mcp-server-markdown, mcp-server-markdown
- Stars
- 8
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Oct 11, 2026
- License
- MIT
What is markdown MCP?
markdown enables AI clients to search, navigate, and extract structured content from local markdown files including headings, sections, and code blocks. It exposes 6 tools, such as list_files, search_docs, get_section.
Summary generated from the project's README
About markdown MCP server
Navigating internal project wikis, architecture decision records, and onboarding guides becomes easier when your AI client understands the structure of your documentation. This server allows developers to interact with local markdown files through specialized tools that recognize more than just raw text. It provides the ability to parse YAML frontmatter, identify specific code blocks, and navigate document hierarchies using headings.
Users can connect this server to Claude Desktop, Cursor, or VS Code Copilot using npx. Unlike standard filesystem servers that treat files as flat strings, this implementation uses tools like get_section to extract specific parts of a document and list_headings to generate a table of contents. It operates entirely on your local machine without requiring any API keys or authentication, making it a private way to index your own knowledge base.
By using search_docs, an assistant can perform case-insensitive full-text searches across your entire directory to find relevant information. The server also includes find_code_blocks to isolate programming examples by language, such as TypeScript, helping you quickly retrieve technical snippets from your documentation.
What you can do with it
- 1Extract specific documentation sectionsAsk your AI to retrieve a particular part of a file based on its heading.
- 2Locate programming examplesFind all code snippets written in a specific language within your markdown files.
- 3Search internal knowledge basesPerform a full-text search across all your local markdown files to find specific terms.
- 4View document structuresGenerate a table of contents to understand the organization of a markdown file.
Written from the project's README. Every use case is checked against a quote from it.
How to install markdown MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall markdown MCP in Claude Code
$ claude mcp add mcp-server-markdown -- npx -y mcp-server-markdownInstall markdown MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server-markdown": {
"command": "npx",
"args": [
"-y",
"mcp-server-markdown"
]
}
}
}Install markdown MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server-markdown": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-server-markdown"
]
}
}
}Install markdown MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server-markdown","type":"stdio","command":"npx","args":["-y","mcp-server-markdown"]}'Install markdown MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server-markdown": {
"command": "npx",
"args": [
"-y",
"mcp-server-markdown"
]
}
}
}Install markdown MCP in Codex
$ codex mcp add mcp-server-markdown -- npx -y mcp-server-markdownInstall markdown MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server-markdown] command = "npx" args = ["-y", "mcp-server-markdown"]
Install markdown MCP in Gemini CLI
$ gemini mcp add -s user mcp-server-markdown npx -- -y mcp-server-markdownInstall markdown MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server-markdown": {
"command": "npx",
"args": [
"-y",
"mcp-server-markdown"
]
}
}
}markdown MCP tools 6
Detected from the READMElist_filessearch_docsget_sectionlist_headingsfind_code_blocksget_frontmatter
| list_files | — | |
| search_docs | — | |
| get_section | — | |
| list_headings | — | |
| find_code_blocks | — | |
| get_frontmatter | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableofershap/mcp-server-markdown is public and reachablegithub.com/ofershap/mcp-server-markdown ↗Pass
- Package names this repository as its sourcemcp-server-markdown names ofershap/mcp-server-markdown as sourcenpmjs.com/package/mcp-server-markdown ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-11github.com/ofershap/mcp-server-markdown ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcp-server-markdownPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-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
.mdfiles, 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
| Tool | What it does |
|---|---|
list_files |
List all .md files in a directory recursively (sorted alphabetically) |
search_docs |
Full-text search across all .md files (case-insensitive, up to 50 results) |
get_section |
Extract a section by heading until the next heading of same/higher level |
list_headings |
List all headings as a table of contents |
find_code_blocks |
Find fenced code blocks, optionally filter by language (e.g. typescript) |
get_frontmatter |
Parse 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
markdown MCP questions
How do I add markdown MCP to Claude Code?
Run claude mcp add mcp-server-markdown -- npx -y mcp-server-markdown in your terminal. Add --scope user to make it available in every project.
How do I add markdown MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does markdown MCP provide?
It exposes 6 tools, including list_files, search_docs, get_section, list_headings, find_code_blocks.
How is this different from the filesystem MCP?
While filesystem tools read raw files, this server understands the structure of markdown, including headings, sections, fenced code, and frontmatter.
Do I need API keys?
No, the server works with local paths and does not require any authentication.
How is this different from Context7?
Context7 is used for pulling published library docs from npm, whereas this server indexes markdown files already present on your local disk.