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.

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

• 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

• 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

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

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

# 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 .

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]"

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

mkdocs-mcp

The server will:

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

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

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

Read a specific markdown file with metadata:

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

Get a list of all available documentation:

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

Combines keyword and semantic search:

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

Fast text-based search:

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

Semantic similarity search:

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

Get information about the current MkDocs project:

{}  # No parameters required

Restart the MkDocs development server:

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

Rebuild the search index:

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

Access to document metadata and structure:

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

Generate intelligent search queries for documentation:

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

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.

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

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"]
    }
  ]
}

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"
      }
    }
  }
}

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

1. MkDocs server not starting:

   # Check if MkDocs is installed
   mkdocs --version
   
   # Install if missing
   pip install mkdocs

2. Vector search not working:

   # Install optional dependencies
   pip install sentence-transformers

3. Permission errors:

   # Check file permissions
   ls -la mkdocs.yml

Run with verbose output:

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

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

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 .

MIT License - see LICENSE file for details.

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

• 📚 Documentation
• 🐛 Issue Tracker
• 💡 Feature Requests

Built with ❤️ by dou inc.