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.

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',
        },
      },
    ],
  ],
};

2. Create the API Endpoint

Choose your deployment platform:

Vercel

Create api/mcp.js:

import { createVercelHandler } from 'docusaurus-plugin-mcp-server/adapters';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default createVercelHandler({
  docsPath: path.join(__dirname, '../build/mcp/docs.json'),
  indexPath: path.join(__dirname, '../build/mcp/search-index.json'),
  name: 'my-docs',
  baseUrl: 'https://docs.example.com',
});

Add to vercel.json:

{
  "functions": {
    "api/mcp.js": {
      "includeFiles": "build/mcp/**"
    }
  },
  "rewrites": [
    { "source": "/mcp", "destination": "/api/mcp" }
  ]
}

Netlify

Create netlify/functions/mcp.js:

import { createNetlifyHandler } from 'docusaurus-plugin-mcp-server/adapters';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export const handler = createNetlifyHandler({
  docsPath: path.join(__dirname, '../../build/mcp/docs.json'),
  indexPath: path.join(__dirname, '../../build/mcp/search-index.json'),
  name: 'my-docs',
  baseUrl: 'https://docs.example.com',
});

Add to netlify.toml:

[build]
  publish = "build"

[functions]
  directory = "netlify/functions"
  included_files = ["build/mcp/**"]

[[redirects]]
  from = "/mcp"
  to = "/.netlify/functions/mcp"
  status = 200

Cloudflare Workers

Cloudflare Workers can't access the filesystem, so you need to import the data directly:

import { createCloudflareHandler } from 'docusaurus-plugin-mcp-server/adapters';
import docs from '../build/mcp/docs.json';
import searchIndex from '../build/mcp/search-index.json';

export default {
  fetch: createCloudflareHandler({
    docs,
    searchIndexData: searchIndex,
    name: 'my-docs',
    baseUrl: 'https://docs.example.com',
  }),
};

3. Build and Deploy

npm run build
# Deploy to your platform

4. Connect Your AI Tool

Claude Code:

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

Cursor / VS Code:

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

5. Add an Install Button (Optional)

Add a dropdown button to your docs site so users can easily install the MCP server in their AI tool:

import { McpInstallButton } from 'docusaurus-plugin-mcp-server/theme';

function NavbarItems() {
  return (
    <McpInstallButton
      serverUrl="https://docs.example.com/mcp"
      serverName="my-docs"
    />
  );
}

The button shows a dropdown with copy-to-clipboard configurations for all supported MCP clients.

Light Mode	Dark Mode

Props:

Prop	Type	Default	Description
`serverUrl`	`string`	required	Your MCP server endpoint URL
`serverName`	`string`	required	Name for the MCP server
`label`	`string`	(none)	Button label. If omitted, shows only the MCP icon
`headerText`	`string`	`"Choose your AI tool:"`	Text shown at the top of the dropdown
`className`	`string`	`""`	Optional CSS class
`clients`	`ClientId[]`	All HTTP-capable	Which clients to show

MCP Tools

The server exposes two tools for AI agents:

`docs_search`

Search across documentation with relevance ranking. Returns matching documents with URLs, snippets, and relevance scores.

{
  "name": "docs_search",
  "arguments": {
    "query": "authentication",
    "limit": 5
  }
}

Parameter	Type	Default	Description
`query`	`string`	required	Search query
`limit`	`number`	`5`	Max results (1-20)

Response includes:

Full URL for each result (use with docs_fetch)
Title and relevance score
Snippet of matching content
Matching headings

`docs_fetch`

Retrieve full page content as markdown. Use this after searching to get the complete content of a specific page.

{
  "name": "docs_fetch",
  "arguments": {
    "url": "https://docs.example.com/docs/authentication"
  }
}

Parameter	Type	Description
`url`	`string`	Full URL of the page (from search results)

Response includes:

Page title and description
Table of contents with anchor links
Full markdown content

Plugin Options

Option	Type	Default	Description
`outputDir`	`string`	`'mcp'`	Output directory for MCP artifacts (relative to build dir)
`contentSelectors`	`string[]`	`['article', 'main', ...]`	CSS selectors for finding content
`excludeSelectors`	`string[]`	`['nav', 'header', ...]`	CSS selectors for elements to remove
`minContentLength`	`number`	`50`	Minimum content length to consider a page valid
`server.name`	`string`	`'docs-mcp-server'`	Name of the MCP server
`server.version`	`string`	`'1.0.0'`	Version of the MCP server
`excludeRoutes`	`string[]`	`['/404', '/search']`	Routes to exclude (glob patterns)

Default Selectors

Content selectors (in priority order):

['article', 'main', '.main-wrapper', '[role="main"]']

Exclude selectors:

['nav', 'header', 'footer', 'aside', '[role="navigation"]', '[role="banner"]', '[role="contentinfo"]']

Server Configuration

For the runtime adapters:

Option	Type	Required	Description
`docsPath`	`string`	Yes*	Path to `docs.json`
`indexPath`	`string`	Yes*	Path to `search-index.json`
`docs`	`object`	Yes*	Pre-loaded docs (Cloudflare)
`searchIndexData`	`object`	Yes*	Pre-loaded search index (Cloudflare)
`name`	`string`	Yes	Server name
`version`	`string`	No	Server version
`baseUrl`	`string`	No	Base URL for full page URLs in responses

*Use either file paths (Node.js) or pre-loaded data (Workers).

Verifying Your Build

After running npm run build, use the included CLI to verify the MCP output:

npx docusaurus-mcp-verify

This checks that:

All required files exist (docs.json, search-index.json, manifest.json)
Document structure is valid
The MCP server can initialize and load the content

You can specify a custom build directory:

npx docusaurus-mcp-verify ./custom-build

Example output:

🔍 MCP Build Verification
==================================================
Build directory: /path/to/your/project/build

📁 Checking build output...
   ✓ Found 42 documents
   ✓ All required files present
   ✓ File structure valid

🚀 Testing MCP server...
   ✓ Server initialized with 42 documents

✅ All checks passed!

Testing the Endpoint

The easiest way to test your MCP server is with the official MCP Inspector:

npx @modelcontextprotocol/inspector

This opens a visual interface where you can:

Connect to your server URL
Browse available tools
Execute tool calls interactively
View responses in a formatted display

Alternatively, test with curl:

# List available tools
curl -X POST https://docs.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search documentation
curl -X POST https://docs.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"docs_search",
      "arguments":{"query":"getting started"}
    }
  }'

How It Works

flowchart LR
    subgraph Build["Build Time"]
        A[Docusaurus Build] --> B[postBuild Hook]
        B --> C[Extract Content]
        C --> D[Build Search Index]
        D --> E[Write Artifacts]
    end

    subgraph Artifacts["build/mcp/"]
        F[docs.json]
        G[search-index.json]
        H[manifest.json]
    end

    subgraph Runtime["Runtime"]
        I[Serverless Function]
        J[MCP Server]
    end

    subgraph Clients["AI Agents"]
        K[Claude]
        L[Cursor]
        M[Other MCP Clients]
    end

    E --> F & G & H
    F & G --> I
    I --> J
    K & L & M <-->|MCP Protocol| J

The plugin operates in two phases:

Build Time: During docusaurus build, the plugin's postBuild hook processes all rendered HTML pages, extracts content, converts to markdown, builds a FlexSearch index, and outputs artifacts to build/mcp/.

Runtime: A serverless function loads the pre-built artifacts and handles MCP JSON-RPC requests from AI agents. The server is stateless and fast since all indexing happens at build time.

Features

Full-text Search - FlexSearch-powered search with relevance ranking
Page Retrieval - Get complete page content as clean markdown
Platform Adapters - Pre-built adapters for Vercel, Netlify, and Cloudflare Workers
CORS Support - All adapters include CORS headers for browser-based clients
Build-time Processing - Extracts content from rendered HTML, capturing React component output
Zero Runtime Docusaurus Dependency - The MCP server runs independently

Local Development

Run a local HTTP server for testing:

// mcp-server.mjs
import http from 'http';
import { McpDocsServer } from 'docusaurus-plugin-mcp-server';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const server = new McpDocsServer({
  docsPath: path.join(__dirname, 'build/mcp/docs.json'),
  indexPath: path.join(__dirname, 'build/mcp/search-index.json'),
  name: 'my-docs',
  baseUrl: 'http://localhost:3000',
});

http.createServer(async (req, res) => {
  if (req.method === 'OPTIONS') {
    res.writeHead(204, {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    });
    res.end();
    return;
  }

  if (req.method !== 'POST') {
    res.writeHead(405);
    res.end();
    return;
  }

  await server.handleHttpRequest(req, res);
}).listen(3456, () => {
  console.log('MCP server at http://localhost:3456');
});

Connect Claude Code:

claude mcp add --transport http my-docs http://localhost:3456

API Reference

Main Exports

import {
  // Docusaurus plugin (default export)
  mcpServerPlugin,

  // MCP Server class
  McpDocsServer,

  // Tool definitions
  docsSearchTool,
  docsFetchTool,

  // Utilities
  htmlToMarkdown,
  extractContent,
  extractHeadingsFromMarkdown,
  buildSearchIndex,

  // Provider types (for custom implementations)
  loadIndexer,
  loadSearchProvider,
  FlexSearchIndexer,
  FlexSearchProvider,

  // Default options
  DEFAULT_OPTIONS,
} from 'docusaurus-plugin-mcp-server';

Adapter Exports

import {
  createVercelHandler,
  createNetlifyHandler,
  createCloudflareHandler,
  generateAdapterFiles,
} from 'docusaurus-plugin-mcp-server/adapters';

Theme Exports

import {
  McpInstallButton,
  type McpInstallButtonProps,
} from 'docusaurus-plugin-mcp-server/theme';

Requirements

Node.js >= 20
Docusaurus 3.x

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
examples/basic-docs		examples/basic-docs
img		img
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.mise.toml		.mise.toml
.npmignore		.npmignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

docusaurus-plugin-mcp-server

Installation

Quick Start

1. Add the Plugin

2. Create the API Endpoint

3. Build and Deploy

4. Connect Your AI Tool

5. Add an Install Button (Optional)

MCP Tools

`docs_search`

`docs_fetch`

Plugin Options

Default Selectors

Server Configuration

Verifying Your Build

Testing the Endpoint

How It Works

Features

Local Development

API Reference

Main Exports

Adapter Exports

Theme Exports

Requirements

License

About

Uh oh!

Releases 8

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

docusaurus-plugin-mcp-server

Installation

Quick Start

1. Add the Plugin

2. Create the API Endpoint

3. Build and Deploy

4. Connect Your AI Tool

5. Add an Install Button (Optional)

MCP Tools

docs_search

docs_fetch

Plugin Options

Default Selectors

Server Configuration

Verifying Your Build

Testing the Endpoint

How It Works

Features

Local Development

API Reference

Main Exports

Adapter Exports

Theme Exports

Requirements

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Contributors

Uh oh!

Languages

`docs_search`

`docs_fetch`