Mkdocs

Provides an experimental MCP server that builds and serves MkDocs content through a dedicated runtime, enabling real-time preview and processing of documentation.

other

8

GitHub Stars

other

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ubaumann-mkdocs-mcp": {
      "command": "uv",
      "args": [
        "run",
        "mkdocs-mcp",
        "-mt",
        "stdio"
      ],
      "env": {
        "MKDOCS_PROJECT_PATH": "path/to/your/mkdocs/project"
      }
    }
  }
}

You can run an MCP server directly inside your MkDocs workflow to serve or transform documentation content. This MCP integration lets you build and serve content through a dedicated server process while you work in MkDocs, enabling a streamlined authoring and preview flow.

How to use

To use the MCP server alongside your MkDocs project, start the server process and then interact with it from your MCP client. The server runs as a background task that builds or serves content according to your configuration, allowing you to preview changes in real time.

How to install

Prerequisites you need before starting: install the runtime tool that manages dependencies used by the MCP workflow, and ensure you have MkDocs installed if you are building documentation locally.

Step by step commands you should run in your project directory:

# Ensure you have the runtime tool installed (example uses uvx-style tooling)
# Install or verify MkDocs project dependencies if needed
# Start the MCP server for MkDocs with standard IO mode
uv run mkdocs-mcp -mt stdio

Additional configuration and notes

The MCP integration is configured to work with your MkDocs project by including an mcp plugin in your MkDocs configuration. You can set how the content is named, whether to combine pages, and how the output is handled.

If you are using Claude Desktop with WSL to run the MCP workflow, you can configure a startup command that executes within the WSL environment. A common approach is to run the runtime command inside WSL to invoke the MCP server from your Windows host.

For development and debugging, you can inspect the MCP server directly by invoking its internal run target. This is useful to understand how the server processes input and generates output.

Usage patterns and tips

Use the stdio mode when you want tight integration with MkDocs and immediate feedback while editing content.
If you need to point the server at a specific MkDocs project location, you can set an environment variable to communicate the path to your project.
When starting the server from Windows with WSL, ensure your startup command uses the WSL shell and the correct paths to your project files.

Available tools

MCP server runner

Runs the MCP server alongside MkDocs, handling build and serve operations according to the configured settings.

MkDocs plugin integration

Provides a plugin that connects MkDocs with the MCP server to enable enhanced building and serving of content.

Server inspection tool

Allows direct inspection of the MCP server internals for development and debugging.