{ "markdown": "# mcp-server-markdown\n\n[![npm version](https://img.shields.io/npm/v/mcp-server-markdown.svg)](https://www.npmjs.com/package/mcp-server-markdown)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-server-markdown.svg)](https://www.npmjs.com/package/mcp-server-markdown)\n[![CI](https://github.com/ofershap/mcp-server-markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/ofershap/mcp-server-markdown/actions/workflows/ci.yml)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Agent Plugins](https://img.shields.io/badge/Agent_Plugins-1.0.0-0ea5e9.svg)](https://agent-plugins.org)\n\nSearch, navigate, and extract content from local markdown files. Full-text search, section extraction, heading navigation, code block discovery, and frontmatter parsing.\n\n```bash\nnpx mcp-server-markdown\n```\n\n> Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Reads local `.md` files, no auth needed.\n\n

\n \"Install\n  \n \"Add\n

\n\n![MCP server for searching and navigating markdown documentation](assets/demo.gif)\n\nDemo built with remotion-readme-kit\n\n## Why\n\nTools 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.\n\n## Tools\n\n| Tool | What it does |\n| ------------------ | -------------------------------------------------------------------------- |\n| `list_files` | List all .md files in a directory recursively (sorted alphabetically) |\n| `search_docs` | Full-text search across all .md files (case-insensitive, up to 50 results) |\n| `get_section` | Extract a section by heading until the next heading of same/higher level |\n| `list_headings` | List all headings as a table of contents |\n| `find_code_blocks` | Find fenced code blocks, optionally filter by language (e.g. typescript) |\n| `get_frontmatter` | Parse YAML frontmatter metadata at the start of a file |\n\n## Quick Start\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"markdown\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-markdown\"]\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"markdown\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-markdown\"]\n }\n }\n}\n```\n\n### VS Code\n\nAdd to user settings or `.vscode/mcp.json`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"markdown\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-markdown\"]\n }\n }\n }\n}\n```\n\n## Examples\n\n- \"Search all docs in ./docs for mentions of 'authentication'\"\n- \"Show me the 'API Reference' section from README.md\"\n- \"List all headings in CONTRIBUTING.md\"\n- \"Find all TypeScript code blocks in the docs\"\n- \"What's the frontmatter metadata in this file?\"\n- \"Give me the table of contents for our architecture docs\"\n\n## Agent Plugins\n\nThis repo is an [Agent Plugins](https://agent-plugins.org) 1.0.0 package: `plugin.json`, portable `mcp.json`, and `skills/` ship together with the MCP server.\n\nFor 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.\n\nThe Cursor and VS Code install buttons above still work: they add the same `npx -y mcp-server-markdown` stdio server as manual JSON.\n\n## FAQ\n\n### What is mcp-server-markdown?\n\nAn MCP server that searches and navigates local `.md` files: full-text search, sections by heading, TOC, code blocks, and YAML frontmatter.\n\n### How is this different from Context7?\n\nContext7 pulls published library docs from npm. This server indexes markdown already on your disk (wikis, ADRs, internal guides).\n\n### How is this different from the filesystem MCP?\n\nFilesystem tools read raw files. This server understands headings, sections, fenced code, and frontmatter.\n\n### Can I install it as an Agent Plugin in Cursor?\n\nYes. Use `~/.cursor/plugins/local/mcp-server-markdown` so the bundled `markdown-search` skill loads with the MCP config.\n\n### Do I need API keys?\n\nNo. Paths are local; the agent passes directory and file paths to the tools.\n\n## Development\n\n```bash\ngit clone https://github.com/ofershap/mcp-server-markdown.git\ncd mcp-server-markdown\nnpm install\nnpm test\nnpm run build\n```\n\n## See also\n\nMore MCP servers and developer tools on my [portfolio](https://gitshow.dev/ofershap).\n\n## Author\n\n[![Made by ofershap](https://gitshow.dev/api/card/ofershap)](https://gitshow.dev/ofershap)\n\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0A66C2?style=flat&logo=linkedin&logoColor=white)](https://linkedin.com/in/ofershap)\n[![GitHub](https://img.shields.io/badge/GitHub-Follow-181717?style=flat&logo=github&logoColor=white)](https://github.com/ofershap)\n\n---\n\nREADME built with [README Builder](https://ofershap.github.io/readme-builder/)\n\n## License\n\nMIT © 2026 Ofer Shapira\n", "bytes": 6258, "sha": "e3dee91111215592a234e959d6fc73d3731597df0a693f2285129a2fd48c9e6c", "repo_slug": "ofershap/mcp-server-markdown", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ofershap_markdown_1da0098e/readme" }