MkDocs Material Server

Model Context Protocol (MCP) server for documentation sites built with MkDocs Material.

This MCP server provides tools to search and retrieve documentation from any MkDocs Material-powered documentation site. By default, it connects to the MkDocs Material documentation itself.

Features

• Search Documentation: Find relevant pages across the entire documentation site
• Retrieve Pages: Get full page content in markdown format with source URLs
• Multi-site Support: Configure multiple MkDocs Material sites simultaneously
• Dynamic Tool Generation: Automatically creates MCP tools for each configured site

Prerequisites

Installation Requirements

• Install uv from Astral or the GitHub README
• Install Python 3.10 or newer using uv python install 3.10 (or a more recent version)

Installation

Kiro CLI

Configure the MCP server in your MCP client (like Kiro CLI) configuration (~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "mkdocs": {
      "command": "uvx",
      "args": ["mkdocs-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": ["search_mkdocs-material", "get_mkdocs-material_page"]
    }
  }
}

Custom MkDocs Material Site

To use with your own MkDocs Material-powered documentation:

{
  "mcpServers": {
    "my-docs": {
      "command": "uvx",
      "args": ["mkdocs-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MKDOCS_SITES": "mysite=https://your-docs-site.com"
      },
      "disabled": false,
      "autoApprove": ["search_mysite", "get_mysite_page"]
    }
  }
}

Multiple Sites

Configure multiple MkDocs Material sites:

{
  "mcpServers": {
    "mkdocs-multi": {
      "command": "uvx",
      "args": ["mkdocs-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MKDOCS_SITES": "mkdocs-material=https://squidfunk.github.io/mkdocs-material,mysite=https://your-docs-site.com"
      },
      "disabled": false,
      "autoApprove": ["search_mkdocs-material", "get_mkdocs-material_page", "search_mysite", "get_mysite_page"]
    }
  }
}

Windows Installation

For Windows users, the MCP server configuration format is slightly different:

{
  "mcpServers": {
    "mkdocs": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "mkdocs-mcp@latest",
        "mkdocs-mcp.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
FASTMCP_LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)	WARNING
MKDOCS_SITES	Comma-separated list of site configurations in format key=url	mkdocs-material=https://squidfunk.github.io/mkdocs-material

Performance

Large Documentation Sites: Sites with very large search indexes use async loading with a 1.5-second timeout:

• First search returns a "loading" message if index isn't ready
• The LLM can retry the search (index loads in background)
• Once loaded, the index is cached and searches are instant

Search Capabilities

This MCP server provides basic search functionality:

• Phrase matching: Exact phrase matches are prioritized (highest relevance)
• Word matching: Falls back to matching individual words when exact phrases don't match
• Scoring: Results are ranked by relevance (exact matches first, then by word count)

The LLM interprets search results and provides meaningful answers, making up for the simpler search algorithm with intelligent result processing.

Corporate Network Support

For corporate environments with proxy servers:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "HTTP_PROXY": "http://proxy.company.com:8080"
  }
}

For authenticated proxies:

{
  "env": {
    "HTTPS_PROXY": "http://username:[email protected]:8080"
  }
}

Basic Usage

Example queries:

• "Search MkDocs Material documentation for admonitions"
• "How do I use code blocks in MkDocs Material?"
• "What are the customization options for MkDocs Material?"

About MkDocs Material

MkDocs Material is a powerful documentation framework built on top of MkDocs. This MCP server works with any documentation site built using MkDocs Material.

Development

From Source

git clone https://github.com/ojacques/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e .
mkdocs-mcp

Running Tests

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=mkdocs_mcp --cov-report=html

Tests are automatically run on push and pull requests via GitHub Actions.

Publishing

This package is automatically published to PyPI when a new release is created on GitHub:

1. Update version in pyproject.toml
2. Create a new release on GitHub with a tag (e.g., v0.1.0)
3. GitHub Actions will automatically build and publish to PyPI

Note: Requires PyPI trusted publishing to be configured for the repository.

License

MIT