docusaurus-plugin

This MCP server plugin enables AI agents and tooling to query your Docusaurus documentation through a dedicated MCP endpoint. After building your site, the plugin exposes two main tools through the MCP API: docs_search and docs_fetch. docs_search lets an AI agent search across your documentation with a query and returns relevant pages along with URLs, titles, snippets, and relevance scores. Use docs_fetch to retrieve the full content of a specific page in Markdown by providing the page URL obtained from a search result. The server is designed to integrate with clients such as Claude, Cursor, or VS Code MCP integrations, enabling seamless discovery and retrieval of your docs content.

To use the MCP endpoint, ensure your deployment exposes an accessible URL (for example https://docs.example.com/mcp). You can add the server to your AI tool configuration by specifying the server URL in the MCP client settings. The plugin also provides a ready-made install button for your site that outputs the necessary configurations for common MCP clients. When configured, you can perform a search like a natural-language query (e.g., authentication) and then fetch the full page content for any result you want to review in detail.

Prerequisites:

• Node.js and npm installed (recommended LTS version)
• A Docusaurus project configured to use the docusaurus-plugin-mcp-server plugin

1. Install the MCP server plugin in your Docusaurus project (as a regular plugin):

npm install docusaurus-plugin-mcp-server

2. Configure the plugin in your docusaurus.config.js, providing a server block as shown in the Quick Start of the README:

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

3. Build the documentation so that docs.json and search-index.json are generated:

npm run build

4. Start the MCP server:

• If you are hosting the MCP server separately, run your Node-based server script that serves the MCP endpoint (see the mcp_config above for a placeholder command).
• If you are embedding the MCP endpoint in your app, ensure your app starts and exposes the /mcp endpoint as configured by your deployment (Vercel/Netlify/Cloudflare adapters can be used as described in the README).

5. Verify the MCP output using the included verification tool (when applicable) or by hitting the /mcp endpoint and performing a test docs_search query.

Notes:

• Ensure your deployment can access build/mcp/docs.json and build/mcp/search-index.json produced by the Docusaurus build.
• For Cloudflare Workers or other environments, you may need to preload docs.json and search-index.json and adapt the server adapter accordingly.

Tips and common issues:

• If your MCP endpoint cannot access build/mcp/docs.json or build/mcp/search-index.json, verify your build step outputs these files and that the server process has read access to them.
• When deploying to serverless platforms, remember to mount or include the build/mcp directory in the deployment artifact, as the MCP adapters expect these files to exist.
• If you use Cloudflare Workers, you’ll need to preload the documents and search index in the worker script, as filesystem access is not available.
• The server environment variables (PORT, MCP_BASE_URL, DOCS_PATH, INDEX_PATH) can be customized to fit your hosting provider’s conventions. Ensure the MCP_BASE_URL matches the public URL path where the MCP endpoint will be reachable.
• The plugin provides an install button to help users configure their AI tools; consider enabling this in your docs site to improve discoverability.