mkdocs-ask-ai

Make your MkDocs documentation AI-ready. One plugin gives your site everything AI tools need to work with your docs — a "Use with AI" menu for visitors, llms.txt for crawlers, an MCP server for agents, and raw markdown URLs for everything else.

Works with Material for MkDocs and mkdocs-static-i18n out of the box.

Features

"Use with AI" Dropdown

A floating button on every page with:

• Copy page as Markdown — one-click clipboard copy for any AI tool
• View as Markdown — opens the clean .md source in a new tab
• Open in ChatGPT — sends page content directly to ChatGPT via ?q= parameter
• Open in Claude — sends page content directly to Claude via ?q= parameter
• llms.txt — link to the full documentation index

Adapts to light and dark themes automatically. Inspired by 1Password's developer docs.

llms.txt + llms-full.txt

Follows the llms.txt standard to make your documentation discoverable by AI systems:

• llms.txt — structured index with sections, titles, and links to markdown sources
• llms-full.txt — complete documentation in a single file for full-context queries

Direct Markdown Serving

Every page is accessible as clean markdown at its .md URL. No HTML parsing needed — AI tools get exactly what they need.

https://your-site.com/getting-started/index.md

MCP Server

Expose your documentation as an MCP server so AI agents can query it programmatically.

Tools:

Transports:

Every page is also registered as an MCP resource (docs://site-name/path/to/page.md).

i18n Support

Full support for multilingual sites via mkdocs-static-i18n. Each locale gets its own:

• llms.txt and llms-full.txt
• Markdown files at locale-prefixed URLs
• MCP server tools with locale parameter
• docs-index.json with all locales merged

Comparison

Installation

pip install mkdocs-ask-ai

With MCP server support:

pip install mkdocs-ask-ai[mcp]

Quick Start

Add to your mkdocs.yml:

plugins:
  - ask-ai:
      sections:
        "Getting Started":
          - index.md: "Introduction"
          - quickstart.md: "Quick start guide"
        "API Reference":
          - api/*.md

That's it. Your site now has:

• llms.txt and llms-full.txt at the site root
• .md URLs for every page
• "Use with AI" dropdown on every page

Configuration

Basic Options

plugins:
  - ask-ai:
      sections: {}                      # Section names mapped to file patterns (glob supported)
      markdown_description: ""          # Description included in llms.txt header
      enable_ai_menu: true              # Show "Use with AI" dropdown
      ai_menu_button_text: "Use with AI"
      enable_chatgpt: true              # Show "Open in ChatGPT" item
      enable_claude: true               # Show "Open in Claude" item
      enable_markdown_urls: true        # Serve .md files alongside HTML
      enable_llms_txt: true             # Generate llms.txt
      enable_llms_full: true            # Generate llms-full.txt

MCP Server Options

plugins:
  - ask-ai:
      enable_mcp: true                  # Enable MCP server + docs-index.json
      mcp_path: "/mcp"                  # URL path for streamable HTTP
      mcp_port: 8808                    # Port for MCP HTTP server

When enable_mcp is set and you run mkdocs serve, the MCP server starts automatically alongside the dev server at http://127.0.0.1:8808/mcp.

Section Patterns

Sections support explicit paths, descriptions, and glob patterns:

sections:
  "Infrastructure":
    - infrastructure/index.md: "Infrastructure overview"
    - infrastructure/proxmox.md: "Proxmox hypervisor"
    - infrastructure/*.md              # glob — include all .md files
  "API":
    - api/*.md

Using the MCP Server

With mkdocs serve (recommended for development)

When enable_mcp: true is set, running mkdocs serve automatically starts the MCP server on port 8808. Add this to your .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "my-docs": {
      "type": "sse",
      "url": "http://127.0.0.1:8808/sse"
    }
  }
}

With Claude Desktop / Cursor (stdio)

For stdio transport, build your site first and point to the output directory. Requires mkdocs-ask-ai to be installed in the environment (pip install mkdocs-ask-ai[mcp]):

{
  "mcpServers": {
    "my-docs": {
      "command": "mkdocs-ask-ai",
      "args": ["mcp", "--site-dir", "./public"]
    }
  }
}

If mkdocs-ask-ai is installed in a virtualenv, use the full path to the binary (e.g. /path/to/.venv/bin/mkdocs-ask-ai).

Standalone HTTP Server

mkdocs-ask-ai mcp --transport http --port 8808 --site-dir ./public

CLI Reference

mkdocs-ask-ai mcp [OPTIONS]

Options:
  --site-dir PATH              Built site directory (default: ./public)
  --transport {stdio,http,sse} Transport type (default: stdio)
  --port PORT                  HTTP/SSE port (default: 8808)
  --host HOST                  HTTP/SSE host (default: 127.0.0.1)

Hosting Considerations

For static hosting, the llms.txt, markdown URLs, and "Use with AI" dropdown work out of the box. Only the MCP server requires a running process.

With mkdocs-static-i18n

Place ask-ai before i18n in the plugins list:

plugins:
  - ask-ai:
      sections:
        "Docs":
          - "*.md"
  - i18n:
      docs_structure: suffix
      languages:
        - locale: en
          default: true
          name: English
        - locale: ru
          name: Russian

Output per locale:

public/
  llms.txt              # English
  llms-full.txt
  docs-index.json       # merged index (all locales)
  ru/
    llms.txt            # Russian
    llms-full.txt

License

MIT — see LICENSE.

Originally inspired by mkdocs-llmstxt-md by Nok Lam Chan.