scalvert/docusaurus-plugin-mcp-server

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 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:

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, or one #section, as Markdown with a table of contents. Accepts links as agents copy them (root-relative, trailing slash, .md) and, when skills are served, skill:// URIs.

Details in MCP tools.

Documentation

• Getting started: install, build, and run the server locally
• Deploy: platform guides, deployment checks, and troubleshooting
• Guides: Agent Skills, Writing for agents, Agent guides, 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

Besides docusaurus-plugin-mcp-server (the API reference), skills/guides/ has a step-by-step skill for each procedure on the docs site: setting up the plugin, deploying to Vercel, Netlify, Cloudflare Workers, or a static host, and writing agent guides. They’re compiled from the site’s pages, so edit the page, not the skill.