Markdown Navigation MCP

An MCP server that provides efficient navigation and reading of large markdown files using ctags to reduce context usage

Efficiently navigate large markdown files (2,000+ lines) without loading entire documents into context. Reduces token usage by 50-80% when working with documentation, planning files, and technical specifications.

Prerequisites: Universal Ctags and Go 1.21+

# Install ctags brew install universal-ctags # macOS sudo apt install universal-ctags # Ubuntu/Debian sudo dnf install universal-ctags # Fedora # Build and install git clone <repo-url> cd markdown-mcp go build -o mdnav-server ./cmd/server sudo cp mdnav-server /usr/local/bin/

Configure Claude Code(~/claude.json):

{ "mcpServers": { "markdown-nav": { "command": "mdnav-server" } } }

- Zero-configuration: Automatic ctags execution on-demand
- Smart caching: Sub-microsecond responses for repeated queries
- Auto-invalidation: Cache updates when files change
- Selective reading: Load only the sections you need
- Tree navigation: View document structure without reading content
- Pattern matching: Find sections by regex patterns
- Depth control: Limit tree/section depth for focused views

Display document structure as tree (ASCII or JSON format).

- file_path: Path to markdown file
- format: "ascii" or "json" (default: "json")
- max_depth: Limit tree depth 1-6 (default: 2 shows H1+H2)
- section_name_pattern: Regex to filter sections

Get line number boundaries for a specific section.

- file_path: Path to markdown file
- section_heading: Exact heading text (without # symbols)

- file_path: Path to markdown file
- section_heading: Exact heading text (without # symbols)
- max_subsection_levels: Limit subsection depth (omit for all)

- file_path: Path to markdown file
- max_depth: Maximum heading level to show (default: 2)
- section_name_pattern: Regex to filter section names

User: "Review Task 4 from the planning document" Claude uses: 1. markdown_tree to see document structure 2. markdown_section_bounds to find Task 4 location 3. markdown_read_section to read only Task 4 content Result: Complete task analysis using only relevant section (~200 lines instead of 2000)

User: "What testing strategies are documented?" Claude uses: 1. markdown_list_sections with pattern="test" to find testing sections 2. markdown_read_section for each relevant section Result: Comprehensive overview without loading entire document

For more detailed tool usage examples with real output, seeexamples/EXAMPLES.md.

{ "mcpServers": { "markdown-nav": { "command": "mdnav-server", "args": ["-ctags-path", "/custom/path/to/ctags"] } } }

- Install Universal Ctags or use-ctags-pathflag

- Use exact heading text (case-sensitive, no # symbols)
- Runmarkdown_list_sectionsto see available sections

- Ensure file has markdown headings (#, ##, ###, ####)
- Verify Universal Ctags (not Exuberant) is installed

- Restart MCP server to clear cache (auto-invalidates on file changes)

For implementation details, architecture, and contributing guidelines, seeCLAUDE.md.

go test ./... # Run tests golangci-lint run # Lint code go build ./cmd/server # Build server

This project is licensed under theGNU General Public License v3.0.

A VS Code extension with a GUI for the agentic-tools-mcp server, enhancing task and memory management.