Skip to main content

Getting started

This page takes you from an existing Docusaurus 3 site to an MCP server running on your machine. Deploying it is covered in Deploy.

Let your AI agent do it

This page is also an agent guide. Install this project's skills with npx skills add scalvert/docusaurus-plugin-mcp-server, or connect your agent to this site's MCP endpoint (https://docusaurus-plugin-mcp-server.vercel.app/mcp), and ask it to set up the plugin. It follows these steps and checks each one.

Done when:

curl http://localhost:3456 returns the server status with "initialized": true and a docCount above 0.

  • A Docusaurus 3 site. Check: npm ls @docusaurus/core shows a 3.x version.
  • Node.js 22 or later. Check: node --version.

1. Install the plugin​

npm install docusaurus-plugin-mcp-server
Check:

npm ls docusaurus-plugin-mcp-server lists the package.

2. Add it to your config​

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

server.name is the name agents see for your server. Every option is optional; see Plugin options.

Set your site's url

Every page URL the server returns is built from url in docusaurus.config.js at build time. If it still says https://your-docusaurus-site.example.com, agents get links to that. Set it to your production domain before you build for production.

Check:

docusaurus.config.js lists 'docusaurus-plugin-mcp-server' under plugins, and url is the site's production domain.

3. Build and verify​

npm run build
npx docusaurus-mcp-verify

The build writes the artifact bundle to build/mcp/bundle.json. docusaurus-mcp-verify checks that the bundle is valid and that a server can start from it:

📁 Checking build output...
✓ Found 42 documents
✓ Artifact bundle is valid

🚀 Testing MCP server...
✓ Server "my-docs" initialized with 42 documents and 1 skill(s)

✅ All checks passed!

To run the check on every build, add it as a postbuild script:

{
"scripts": {
"build": "docusaurus build",
"postbuild": "docusaurus-mcp-verify"
}
}
Check:

npx docusaurus-mcp-verify ends with ✅ All checks passed!

4. Run the server locally​

The Node adapter serves the bundle straight from build/mcp. Save this next to docusaurus.config.js:

// mcp-server.mjs
import { createNodeServer } from 'docusaurus-plugin-mcp-server/adapters/node';

createNodeServer({
artifactsDir: './build/mcp',
baseUrl: 'http://localhost:3000',
}).listen(3456, () => {
console.log('MCP server at http://localhost:3456');
});
node mcp-server.mjs

Check it's up. A GET returns the server status:

curl http://localhost:3456
{
"name": "my-docs",
"version": "1.0.0",
"initialized": true,
"docCount": 42,
"skillCount": 1,
"baseUrl": "http://localhost:3000",
"searchProvider": "local"
}
Check:

curl http://localhost:3456 returns JSON with "initialized": true.

5. Connect an agent​

Point an MCP client at the local server. For Claude Code:

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

Then ask it something your docs answer. Connecting AI tools covers Cursor, VS Code, and other clients, and Testing the endpoint shows how to call the tools directly.

The local server reads the bundle once at startup. After you rebuild, restart it.

Check:

The client lists my-docs among its MCP servers, and asking it about the docs returns an answer that cites a docs page.

Next steps​

  1. Deploy the endpoint. Pick your host in Deploy. Each guide is a complete setup: the function file, the routing config, and how to check it works.
  2. Add the install button so readers can connect their own tools: Install button.
  3. Tune it: search ranking, Agent Skills, or your own search provider.