home / mcp / mkdocs mcp server
Provides an MCP server for MkDocs docs enabling hybrid search, document access, and agent interaction.
Configuration
View docs{
"mcpServers": {
"douinc-mkdocs-mcp-plugin": {
"command": "mkdocs-mcp",
"args": [],
"env": {
"MCP_PORT": "AUTO",
"MKDOCS_PORT": "8000"
}
}
}
}You can run an MCP server that auto-detects MkDocs projects, launches the MkDocs development server, and provides advanced search, document access, and agent interaction capabilities. This lets you query your docs with keyword or semantic search, read documents with metadata, and run MCP-compatible clients against your MkDocs content.
Start the MCP server for your MkDocs project from any directory that contains a MkDocs configuration. The server will detect your MkDocs setup, launch the MkDocs development server, start the MCP interface for agents, and index your documentation for fast search. You can then use an MCP client to perform hybrid searches, read documents with metadata, list available documents, and restart or rebuild the search index as needed.
Prerequisites you need before starting: - Python and/or Node tooling as described below - Access to the shell or terminal in your project directory - MkDocs installed (to run the docs locally)
# Install and run in one command (recommended)
uvx mkdocs-mcp-plugin
# Or install the MCP plugin globally
uv tool install mkdocs-mcp-plugin
# Then run from any MkDocs project
mkdocs-mcpThe server adapts to your MkDocs configuration automatically. Typical MkDocs settings influence the MCP server behavior, including the docs directory and site URL. Adjust the following environment variables to control ports if needed.
# mkdocs.yml
site_name: My Documentation
docs_dir: docs # Custom docs directory
site_url: https://mydocs.example.com
theme:
name: material
plugins:
- search
```
```bash
# Environment control examples
export MKDOCS_PORT=8000
export MCP_PORT=0 # auto-selects an available port- The MCP server provides a read_document operation to fetch a markdown file along with its metadata and the docs directory when needed. - You can list_documents to get all available documentation with titles and paths. - Search supports hybrid (keyword + vector) or vector-only or keyword-only modes, with real-time indexing for full-text search. - You can obtain MkDocs project information and restart the MkDocs server if necessary, keeping your agent interactions smooth.
Use the included MCP tools to manage your documentation and search experience. You can read individual documents, list all documents, perform hybrid searches, conduct keyword or vector searches, fetch MkDocs project info, restart the MkDocs server, and rebuild the search index.
The server includes robust error handling for missing MkDocs configurations, invalid settings, or search failures. If the MkDocs server cannot start, you can fall back to MCP-only mode and still serve agent requests. If vector search dependencies are missing, the server will gracefully fall back to keyword search.
Run the MCP server in a trusted environment. Ensure that port mappings and file access permissions are correctly configured to prevent unauthorized access to your documentation content.
- Real-time indexing keeps search results up to date as documents change. - Hybrid search provides fast keyword results with contextual semantic understanding for better relevance. - The MCP interface is designed to handle concurrent agent connections safely and efficiently.
Read a specific markdown document with metadata and optional docs_dir. Returns the file path, metadata, and content.
List all available documentation with titles and paths, honoring nested directories.
Perform a hybrid search combining keyword and vector (semantic) methods for best results.
Perform a fast, keyword-based search over the indexed content.
Perform a semantic similarity search over document embeddings.
Retrieve information about the current MkDocs project, including docs_dir and site configuration.
Restart the MkDocs development server to apply changes or recover from issues.
Rebuild the full-text search index for accurate results.