loading…
Search for a command to run...
loading…
Enables AI assistants to access and search MkDocs documentation through tools for full-text search, page navigation, and code block extraction. It serves docume
Enables AI assistants to access and search MkDocs documentation through tools for full-text search, page navigation, and code block extraction. It serves documentation pages as readable resources and provides structural outlines to help LLMs navigate documentation content.
Python MkDocs MCP uv License: MIT
A comprehensive example project demonstrating the integration of MkDocs Material documentation with a Model Context Protocol (MCP) server, showcasing modern Python development practices with uv, devcontainers, and VSCode.
git clone https://github.com/robmatesick/mkdocs-mcp-example.git
cd mkdocs-mcp-example
code .
Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)# Terminal 1: Documentation server
make docs-serve
# Terminal 2: MCP server
make mcp-server
Visit http://localhost:8000 to see your documentation!
mkdocs-mcp-example/
├── 📁 docs/ # Documentation source
│ ├── index.md # Homepage
│ ├── getting-started/ # Setup guides
│ ├── mcp-server/ # MCP documentation
│ ├── api/ # Auto-generated API docs
│ └── examples/ # Usage examples
│
├── 📁 mkdocs-site/ # MkDocs configuration
│ ├── mkdocs.yml # Main configuration
│ ├── pyproject.toml # Dependencies
│ └── docs/ # Theme customizations
│
├── 📁 mcp-server/ # MCP server implementation
│ ├── src/mkdocs_mcp/ # Source code
│ │ ├── server.py # Main server
│ │ ├── resources.py # Resource management
│ │ └── tools.py # Search tools
│ ├── tests/ # Unit tests
│ └── pyproject.toml # Dependencies
│
├── 📁 .devcontainer/ # DevContainer config
├── 📁 .vscode/ # VSCode settings
├── 📁 tests/ # Integration tests
├── pyproject.toml # Workspace configuration
├── Makefile # Development commands
└── README.md # This file
The project includes a comprehensive Makefile with common development tasks:
make setup # Complete development setup
make install # Install dependencies only
make format # Format code with Ruff
make lint # Lint code and fix issues
make typecheck # Run MyPy type checking
make quality # Run all quality checks
make test # Run all tests
make test-cov # Run tests with coverage
make test-watch # Run tests in watch mode
make docs-serve # Start documentation server
make docs-build # Build static documentation
make docs-clean # Clean build artifacts
make mcp-server # Start MCP server
make mcp-test # Run MCP server tests
make dev # Start both docs and MCP server
make clean # Clean all build artifacts
make ci-check # Run all CI checks
graph TB
A[📚 MkDocs Site] --> B[📄 Documentation Files]
B --> C[🤖 MCP Server]
C --> D[🧠 AI Assistant]
D --> E[👥 Users]
F[👨💻 Developer] --> G[🐳 DevContainer]
G --> H[📦 uv Environment]
H --> A
H --> C
I[🔄 CI/CD] --> J[🧪 Tests]
I --> K[🏗️ Build]
I --> L[🚀 Deploy]
The MCP server provides AI assistants with direct access to your documentation:
search_docs - Full-text search across documentationfind_by_title - Find pages by title or headinglist_pages - List all available documentation pagesget_page_outline - Extract page structure and headingssearch_code_blocks - Find and filter code examplesfrom mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# Connect to MCP server
server_params = StdioServerParameters(
command="python",
args=["-m", "mkdocs_mcp.server"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# List available documentation
resources = await session.list_resources()
print(f"Found {len(resources.resources)} pages")
# Search documentation
result = await session.call_tool("search_docs", {
"query": "installation",
"max_results": 5
})
print(result.content[0].text)
docs/ directorymkdocs.ymlmcp-server/src/mkdocs_mcp/make test.devcontainer/Complete documentation is available at:
We welcome contributions! Please see our Contributing Guide for details.
make setupmake ci-checkContainer build fails
# Clean Podman cache and try again
podman system prune -a
# Or rebuild DevContainer from VSCode
# Ctrl+Shift+P -> "Dev Containers: Rebuild Container"
Port conflicts
make docs-serve MKDOCS_PORT=8002
Dependency issues
make clean
make dev-install
See the Troubleshooting Guide for more solutions.
This project is licensed under the MIT License - see the LICENSE file for details.
⭐ Star this repo if you find it helpful!
Built with ❤️ using modern Python development practices.
Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.
{
"mcpServers": {
"mkdocs-mcp-server": {
"command": "npx",
"args": []
}
}
}