docusaurus-plugin-mcp-server

Documentation · Getting started · Deploy guides · Reference

A Docusaurus plugin that exposes an MCP (Model Context Protocol) server endpoint, allowing AI agents like Claude, Cursor, and other MCP-compatible tools to search and retrieve your documentation.

The server speaks MCP 2026-07-28 and still serves clients on 2025-era revisions (the initialize handshake) from the same endpoint. It can also serve Agent Skills that teach agents how to use your docs tools.

The documentation site is built with this plugin. Connect your agent to it:

claude mcp add --transport http docusaurus-plugin-mcp-server https://docusaurus-plugin-mcp-server.vercel.app/mcp

Installation

npm install docusaurus-plugin-mcp-server

Quick Start

1. Add the Plugin

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      'docusaurus-plugin-mcp-server',
      {
        server: {
          name: 'my-docs',
          version: '1.0.0',
        },
      },
    ],
  ],
};

Set url in docusaurus.config.js to your production domain: page URLs in tool results are built from it.

2. Create the API Endpoint

docusaurus build writes the artifact bundle to build/mcp/bundle.json. Serve it from a function at /mcp with createWebRequestHandler, which returns a standard (request: Request) => Promise<Response> for any serverless or edge runtime:

import { createWebRequestHandler } from 'docusaurus-plugin-mcp-server/adapters';
import bundle from '../build/mcp/bundle.json' with { type: 'json' };

export default {
  // Name, version, and site URL come from the build; pass them here to override.
  fetch: createWebRequestHandler({ artifacts: bundle }),
};

Where that file goes and how /mcp is routed to it depends on your host. Each guide is a complete setup:

Platform	Guide
Vercel	Deploy to Vercel
Netlify	Deploy to Netlify
Cloudflare Workers	Deploy to Cloudflare Workers
Deno, Bun	Deploy with Deno or Bun
Node.js, Express	Deploy with Node.js and Express
GitHub Pages, other static hosts	Static hosts

3. Build and Verify

npm run build
npx docusaurus-mcp-verify

4. Connect Your AI Tool

claude mcp add --transport http my-docs https://docs.example.com/mcp

{
  "mcpServers": {
    "my-docs": {
      "url": "https://docs.example.com/mcp"
    }
  }
}

See Connecting AI tools for VS Code, Codex, Gemini CLI, and others, and Install button to give your readers a one-click config.

MCP Tools

• docs_search: BM25-ranked search across your docs. Returns URLs, snippets, and matching headings.
• docs_fetch: one page as Markdown, with a table of contents.

Details in MCP tools.

Documentation

• Getting started: install, build, and run the server locally
• Deploy: platform guides, deployment checks, and troubleshooting
• Guides: Agent Skills, Search, Custom providers, Testing the endpoint
• Reference: Plugin options, Server options, Artifact bundle, API, docusaurus-mcp-verify

The site's source is in website/.

Upgrading

Every major release has a migration guide with before/after code and a checklist an AI agent can run:

• 2.x → 3.0 (not released yet): migrations/2.x-3.0.0.md. Everything it covers is deprecated in 2.2 and still works through 2.x.
• 1.x → 2.0: migrations/1.x-2.0.0.md
• 0.13 → 1.0: migrations/0.13.0-1.0.0.md

Upgrading summarizes what changed in each release line.

Requirements

• Node.js >= 22
• Docusaurus 3.x
• zod >= 4.2

License

MIT

Agent skills

This repository ships agent skill(s) under skills/. Install them into your AI agent with npx skills:

npx skills add -g scalvert/docusaurus-plugin-mcp-server   # global — available in every repo
npx skills add scalvert/docusaurus-plugin-mcp-server      # or scoped to the current repo