docusaurus-plugin-mcp

Expose your Docusaurus docs and OpenAPI specs as an MCP server, so AI agents like Claude, Cursor, and VS Code can search your docs and inspect API endpoints from the editor.

Most docs-MCP tools index prose only. This one treats your OpenAPI specs as a first-class source: it resolves $refs and serves full request and response schemas, so an agent gets the real shape of an endpoint instead of guessing field names.

How it works

The plugin runs at build time. It reads your docs and OpenAPI files and writes a single snapshot (build/<outputDir>/snapshot.json) alongside your site. A small, host-agnostic handler then serves MCP over HTTP from that snapshot.

Docusaurus sites usually deploy as static files, which can't serve a live endpoint. So serving is split out: a CLI for local dev, and a tiny serverless function for production. The plugin's only job is producing the snapshot.

Related MCP server: mcp-docs

Install

npm install docusaurus-plugin-mcp

Configure

// docusaurus.config.js
export default {
  plugins: [
    [
      'docusaurus-plugin-mcp',
      {
        server: { name: 'my-docs', version: '1.0.0' },
        // OpenAPI specs to index, paths relative to the site dir. Optional.
        openapi: [
          { name: 'api', spec: 'openapi/api.json' },
          { name: 'admin', spec: 'openapi/admin.yaml' },
        ],
      },
    ],
  ],
};

Run docusaurus build and you'll get build/mcp/snapshot.json.

Options

Tools

The three *_api tools only appear when you configure openapi. Everything is read-only.

Serve it

Local dev

After a build, serve the snapshot:

npx docusaurus-plugin-mcp serve            # reads build/mcp/snapshot.json on :3100

Or build and serve in one step, without a full Docusaurus build:

npx docusaurus-plugin-mcp serve --site . --openapi api=openapi/api.json

Then point a client at http://localhost:3100/mcp, or inspect it:

npx @modelcontextprotocol/inspector   # connect via Streamable HTTP

Production

Static hosting can't serve a live endpoint, so add one serverless function that imports the snapshot. The handler is a standard Node (req, res). Vercel example:

// api/mcp.ts
import { createNodeHandler } from 'docusaurus-plugin-mcp/server';
import snapshot from '../build/mcp/snapshot.json' assert { type: 'json' };

export default createNodeHandler(snapshot, { name: 'my-docs', version: '1.0.0' });

It's stateless: a fresh server is created per request, so it scales horizontally with no session store. The same handler works in any Node serverless runtime or an Express route. See examples/vercel.

Connect a client

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

// Cursor / VS Code: .cursor/mcp.json or .vscode/mcp.json
{ "mcpServers": { "my-docs": { "url": "https://docs.example.com/mcp" } } }

Programmatic use

import { buildSnapshot, resolveOptions } from 'docusaurus-plugin-mcp';
import { createMcpServer, createNodeHandler, loadSnapshot } from 'docusaurus-plugin-mcp/server';

• buildSnapshot({ siteDir, baseUrl, options }) — build a snapshot in memory.

• createMcpServer(snapshot, opts) — a configured McpServer from the SDK.

• createNodeHandler(snapshot, opts) — a stateless Node request handler.

• loadSnapshot(file) — read a snapshot from disk.

Limitations

• Doc URLs are derived from routeBasePath plus the file path or slug frontmatter. That covers the common cases; exotic routing or path aliases may not match exactly.

• Refreshing happens at build. Rebuild to pick up doc changes. The CLI's build-on-the-fly mode is for dev.

• Runtime targets Node. Web-standard/edge runtimes aren't supported yet.

License

MIT