@devista/docs-mcp

A generic MCP server that gives AI agents (Claude Code, Cursor, etc.) full-text search over any Markdown/MDX documentation folder. Point it at your docs and your AI assistant can search, browse, and read your project documentation during development.

How It Works

The server runs as a local process communicating over stdio (the standard MCP transport). When it starts:

1. Freshness check — compares modification times of your doc files against the last-built index
2. Auto-rebuild — if any file changed (or the index doesn't exist yet), it parses all Markdown/MDX files, strips MDX syntax (imports, JSX component tags), extracts frontmatter, and builds a Flexsearch full-text search index
3. Serve — exposes three MCP tools (search_docs, get_page, list_sections) that agents can call to query your documentation
4. Cached — the index is stored in .docs-mcp/ in your working directory, so subsequent startups are instant if nothing changed

The server understands standard Markdown frontmatter (title, description) and organizes pages into sections based on directory structure (e.g. backend/payments.md belongs to the backend section).

Quick Start

Add to your project's .mcp.json:

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs"]
    }
  }
}

That's it. Restart your AI tool and the docs are queryable.

Usage Examples

Relative path — docs inside your project

When your documentation lives alongside your code:

my-project/
├── src/
├── docs/           <-- your markdown docs
├── .mcp.json
└── package.json

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs"]
    }
  }
}

Relative path — Astro/Starlight project

For documentation sites using Astro Starlight:

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./src/content/docs"]
    }
  }
}

Absolute path — docs in a separate repo or folder

When your docs live outside the current project (e.g. a monorepo or a separate docs repo):

{
  "mcpServers": {
    "project-docs": {
      "command": "npx",
      "args": [
        "-y", "@devista/docs-mcp",
        "--docs", "/Users/me/projects/my-docs/src/content/docs",
        "--name", "project-docs"
      ]
    }
  }
}

Multiple documentation sources

You can register multiple instances for different doc folders:

{
  "mcpServers": {
    "api-docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs/api", "--name", "api-docs"]
    },
    "architecture-docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs/architecture", "--name", "architecture-docs"]
    }
  }
}

Using a config file instead of CLI args

Create .docs-mcp.json in your project root:

{
  "docs": "./src/content/docs",
  "include": ["**/*.md", "**/*.mdx"],
  "exclude": ["**/drafts/**"],
  "name": "my-project-docs"
}

Then your .mcp.json simplifies to:

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp"]
    }
  }
}

Configuration

CLI Args

| Arg | Description | |-----|-------------| | --docs <path> | Path to documentation folder (required unless set in config file) | | --name <name> | Server name shown in MCP clients (default: docs-mcp) |

Config File (.docs-mcp.json)

| Setting | Type | Default | Description | |---------|------|---------|-------------| | docs | string | — | Path to documentation folder (required) | | include | string[] | ["**/*.md", "**/*.mdx"] | Glob patterns for files to index | | exclude | string[] | ["**/node_modules/**"] | Glob patterns for files to skip | | name | string | docs-mcp | Server name shown in MCP clients |

CLI args override config file values. Paths are resolved relative to the working directory.

Tools

search_docs

Full-text search across all documentation pages. Returns ranked results with text excerpts.

• query (string, required) — The search query
• limit (number, optional, default: 5) — Max results to return

get_page

Retrieve the full Markdown content of a specific page, including frontmatter metadata.

• path (string, required) — Page path relative to docs root, without extension (e.g. backend/payments)

list_sections

List all documentation sections and their pages. Returns a structured table of contents. No parameters.

Add to .gitignore

The search index is cached locally. Add this to your .gitignore:

.docs-mcp/

License

MIT