You can run a local MCP server that exposes your markdown documentation to clients. It aggregates docs from multiple sources, provides fast cache-backed search, and ensures safe access to files. This guide shows you how to install, configure, and use Local Docs MCP Server so you can query and read documentation efficiently from your projects and commands.

How to use

After you start the MCP server, you can query it from your MCP client to find and read documentation across sources. Typical actions include: searching for docs by keyword, listing all available docs, and reading a specific markdown file. Use intuitive phrases like “Show docs for routegroup,” “Find documentation about testing,” or “List all available commands.” The server automatically caches the file list for fast responses and watches for changes to invalidate the cache, keeping results fresh.

How to install

Prerequisites: you need Go or a prebuilt binary, and a runtime environment for your platform.

# Install via Go (binary is built and installed to your GOPATH/bin or module cache)
go install github.com/umputun/local-docs-mcp/app@latest

Install via Homebrew (macOS): this provides a convenient, system-wide command.

brew tap umputun/apps
brew install umputun/apps/local-docs-mcp

Build from source (if you prefer to compile locally):

git clone https://github.com/umputun/local-docs-mcp.git
cd local-docs-mcp
make build
make install

Configure Claude by adding a local MCP server entry. You can specify either the command name or an absolute path to the binary.

{
  "mcpServers": {
    "local_docs": {
      "command": "local-docs-mcp"
    }
  }
}

Or with an absolute path:

{
  "mcpServers": {
    "local_docs": {
      "command": "/path/to/local-docs-mcp"
    }
  }
}

Restart Claude Code to load the server.

## Configuration

The MCP server exposes several command line options to tailor how it scans docs and caches results. Typical options include setting the shared docs directory, project docs directory, and root docs inclusion. You can also control cache TTL and max file size to index.

customize documentation directories

local-docs-mcp --shared-docs-dir=~/.claude/commands --docs-dir=documentation

enable root-level markdown scanning

local-docs-mcp --enable-root-docs

exclude directories from project docs scan

local-docs-mcp --exclude-dir=plans --exclude-dir=drafts

multiple exclusions via environment variable

EXCLUDE_DIRS=plans,drafts,archive local-docs-mcp

Available options:
- `--shared-docs-dir` - shared documentation directory (default: `~/.claude/commands`)
- `--docs-dir` - project docs directory (default: `docs`)
- `--enable-root-docs` - scan root-level `*.md` files (default: disabled)
- `--exclude-dir` - directories to exclude from project docs scan (default: `plans`)
- `--cache-ttl` - cache time-to-live (default: `1h`)
- `--max-file-size` - maximum file size in bytes to index (default: `5242880` - 5MB)
- `--dbg` - enable debug logging
```json

Caching and file watching

File list caching is always enabled for fast repeated queries. The cache TTL can be customized to fit your workflow. The system automatically invalidates the cache when documentation files change.

# use default 1h TTL
local-docs-mcp

# custom TTL
local-docs-mcp --cache-ttl=30m

# via environment variable
CACHE_TTL=2h local-docs-mcp

Performance: Cache hits are about 3,000x faster than scanning the filesystem. Cache invalidates within 500ms of changes, with a safety fallback TTL.

## Usage

Once configured, you can query documentation naturally from your MCP client:

- Ask to show docs for a specific topic
- Request a list of all available docs
- Read a particular documentation file by its path or source-prefixed path like `commands:file.md`

## Security

The server includes protections to prevent path traversal, enforces file size limits, validates UTF-8 content, avoids following symlinks outside base directories, and rejects absolute paths.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Available tools

### search\_docs

Search for documentation files by name with fuzzy matching.

### read\_doc

Read a specific documentation file.

### list\_all\_docs

List all available documentation files from all sources.