MkDocs MCP Plugin 🔍

A comprehensive MCP (Model Context Protocol) server for MkDocs documentation that provides intelligent search, retrieval, and integration capabilities for AI agents. This plugin automatically detects MkDocs projects, launches the development server, and provides powerful tools for querying documentation.

Features

🚀 Auto-Detection & Integration

Automatically detects mkdocs.yml or mkdocs.yaml in your project
Launches MkDocs development server alongside the MCP server
Seamless integration with existing MkDocs workflows

🔎 Advanced Search Capabilities

Keyword Search: Fast, accurate text-based search using Whoosh indexing
Vector Search: Semantic search using sentence transformers (all-MiniLM-L6-v2)
Hybrid Search: Combines both keyword and semantic search for optimal results
Real-time Indexing: Automatically indexes markdown files with full-text search

📄 Document Operations

Read individual markdown files with metadata extraction
List all available documentation with titles and paths
Extract headings, titles, and content structure
Support for nested directory structures

🤖 MCP Protocol Compliance

Full MCP server implementation using FastMCP
Tools, resources, and prompts for agent interaction
Structured responses with comprehensive error handling
Support for concurrent agent connections

Installation

Using UV/UVX (Recommended)

Install and run directly with uvx:

# Install and run in one command
uvx mkdocs-mcp-plugin

# Or install globally
uv tool install mkdocs-mcp-plugin

# Then run from any MkDocs project
mkdocs-mcp

Using pip

# Install from source
pip install git+https://github.com/douinc/mkdocs-mcp-plugin.git

# Or clone and install locally
git clone https://github.com/douinc/mkdocs-mcp-plugin.git
cd mkdocs-mcp-plugin
pip install -e .

Development Installation

git clone https://github.com/douinc/mkdocs-mcp-plugin.git
cd mkdocs-mcp-plugin

# Install with UV (recommended)
uv sync --all-extras

# Or with pip
pip install -e ".[dev]"

Usage

Basic Usage

Navigate to any directory containing a mkdocs.yml file and run:

mkdocs-mcp

The server will:

Detect your MkDocs configuration
Start the MkDocs development server (default: http://localhost:8000)
Launch the MCP server for agent interaction
Index your documentation for search

Configuration

The server automatically adapts to your MkDocs configuration:

# mkdocs.yml
site_name: My Documentation
docs_dir: docs  # Custom docs directory
site_url: https://mydocs.example.com
theme:
  name: material
plugins:
  - search

Environment Variables

MKDOCS_PORT: Port for the MkDocs server (default: 8000)
MCP_PORT: Port for the MCP server (auto-selected)

MCP Tools

Document Operations

`read_document`

Read a specific markdown file with metadata:

{
  "file_path": "getting-started.md",
  "docs_dir": "docs"  # Optional, auto-detected
}

`list_documents`

Get a list of all available documentation:

{
  "docs_dir": "docs"  # Optional, auto-detected
}

Search Operations

`search` (Hybrid Search)

Combines keyword and semantic search:

{
  "query": "authentication setup",
  "search_type": "hybrid",  # "keyword", "vector", or "hybrid"
  "max_results": 10
}

`keyword_search`

Fast text-based search:

{
  "query": "configuration options",
  "max_results": 10
}

`vector_search`

Semantic similarity search:

{
  "query": "how to deploy",
  "max_results": 10
}

Utility Tools

`get_mkdocs_info`

Get information about the current MkDocs project:

{}  # No parameters required

`restart_mkdocs_server`

Restart the MkDocs development server:

{
  "port": 8001  # Optional, defaults to 8000
}

`rebuild_search_index`

Rebuild the search index:

{
  "docs_dir": "docs"  # Optional, auto-detected
}

MCP Resources

`mkdocs://documents`

Access to document metadata and structure:

{
  "document_count": 25,
  "docs_dir": "/path/to/docs",
  "documents": [
    {
      "path": "index.md",
      "title": "Welcome",
      "size": 1024
    }
  ]
}

MCP Prompts

`mkdocs-rag-search`

Generate intelligent search queries for documentation:

{
  "topic": "authentication"  # Search topic
}

Advanced Features

Vector Search Dependencies

For semantic search capabilities, ensure these packages are installed:

# Included in default installation
pip install sentence-transformers scikit-learn numpy

If these packages are not available, the server will fall back to keyword-only search.

Custom Index Configuration

The server uses Whoosh for indexing with the following schema:

path: Document file path
title: Document title (from first H1 or filename)
content: Full text content (markdown converted to plain text)
headings: All heading text for structural search

Search Result Structure

All search operations return results in this format:

{
  "success": true,
  "query": "your search query",
  "result_count": 5,
  "results": [
    {
      "path": "docs/api/authentication.md",
      "title": "Authentication Guide",
      "score": 0.95,
      "snippet": "...highlighted excerpt...",
      "search_methods": ["keyword", "vector"]
    }
  ]
}

Integration Examples

Claude Code Configuration

Add to your Claude Code config:

{
  "mcpServers": {
    "mkdocs-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/douinc/mkdocs-mcp-plugin",
        "--with",
        "mkdocs-material",
        "--with",
        "mkdocs-git-revision-date-localized-plugin",
        "--with",
        "mkdocs-minify-plugin",
        "--with",
        "mkdocs-mermaid2-plugin",
        "--with",
        "mkdocs-print-site-plugin",
        "mkdocs-mcp"
      ],
      "env": {
        "MKDOCS_PORT": "8000"
      }
    }
  }
}

Error Handling

The server provides comprehensive error handling:

Missing MkDocs: Graceful fallback to MCP-only mode
Invalid configurations: Clear error messages with suggestions
Search failures: Automatic fallback between search methods
File access errors: Detailed error reporting with context

Troubleshooting

Common Issues

MkDocs server not starting:

# Check if MkDocs is installed
mkdocs --version

# Install if missing
pip install mkdocs

Vector search not working:

# Install optional dependencies
pip install sentence-transformers

Permission errors:

# Check file permissions
ls -la mkdocs.yml

Debug Mode

Run with verbose output:

# Set environment variable for debug output
MKDOCS_DEBUG=1 mkdocs-mcp

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Run tests: uv run pytest
Format code: uv run black . && uv run ruff check --fix .
Submit a pull request

Development Setup

git clone https://github.com/douinc/mkdocs-mcp-plugin.git
cd mkdocs-mcp-plugin

# Install with all dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run linting
uv run ruff check
uv run black --check .

License

MIT License - see LICENSE file for details.

Changelog

v0.1.0

Initial release
MkDocs auto-detection and server integration
Hybrid search with keyword and vector capabilities
Full MCP protocol compliance
UV/UVX support

Support

Built with ❤️ by dou inc.

mkdocs-mcp-plugin