# MkDocs Material MCP Server

Model Context Protocol (MCP) server for documentation sites built with [MkDocs Material](https://squidfunk.github.io/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](https://squidfunk.github.io/mkdocs-material/) 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](https://docs.astral.sh/uv/) from Astral or the [GitHub README](https://github.com/astral-sh/uv)
- 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](https://kiro.dev/docs/cli/)) configuration (`~/.kiro/settings/mcp.json`):

```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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

For authenticated proxies:

```json
{
  "env": {
    "HTTPS_PROXY": "http://username:password@proxy.company.com: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](https://squidfunk.github.io/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

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

### Running Tests

```bash
# 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