Which integrations are available for this server?

Provides intelligent search, retrieval, and document operations for MkDocs documentation projects, including keyword search, semantic vector search, and hybrid search capabilities across [markdown](/mcp/servers/integrations/markdown) files.

MkDocs MCP Plugin 🔍

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.

Features

🚀 Auto-Detection & Integration

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

🔎 Advanced Search Capabilities

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

📄 Document Operations

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

🤖 MCP Protocol Compliance

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

Installation

Using UV/UVX (Recommended)

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

Using pip

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

Development Installation

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

Usage

Basic Usage

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

mkdocs-mcp

The server will:

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

Configuration

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

Environment Variables

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

MCP Tools

Document Operations

`read_document`

Read a specific markdown file with metadata:

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

`list_documents`

Get a list of all available documentation:

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

Search Operations

`search` (Hybrid Search)

Combines keyword and semantic search:

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

`keyword_search`

Fast text-based search:

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

`vector_search`

Semantic similarity search:

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

Utility Tools

`get_mkdocs_info`

Get information about the current MkDocs project:

{} # No parameters required

`restart_mkdocs_server`

Restart the MkDocs development server:

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

`rebuild_search_index`

Rebuild the search index:

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

MCP Resources

`mkdocs://documents`

Access to document metadata and structure:

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

MCP Prompts

`mkdocs-rag-search`

Generate intelligent search queries for documentation:

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

Advanced Features

Vector Search Dependencies

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.

Custom Index Configuration

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

Search Result Structure

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

Integration Examples

Claude Code Configuration

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

Error Handling

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

Troubleshooting

Common Issues

MkDocs server not starting:
# Check if MkDocs is installed mkdocs --version # Install if missing pip install mkdocs
Vector search not working:
# Install optional dependencies pip install sentence-transformers
Permission errors:
# Check file permissions ls -la mkdocs.yml

Debug Mode

Run with verbose output:

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

Contributing

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

Development Setup

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 .

License

MIT License - see LICENSE file for details.

Changelog

v0.1.0

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

Support

Built with ❤️ by dou inc.