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.
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.
curl http://localhost:3456 returns the server status with "initialized": true and a docCount above 0.
- A Docusaurus 3 site. Check:
npm ls @docusaurus/coreshows a 3.x version. - Node.js 22 or later. Check:
node --version.
1. Install the plugin
npm install docusaurus-plugin-mcp-server
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.
urlEvery 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.
If url is still the Docusaurus default, ask the user for their production domain. Don't guess it.
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"
}
}
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"
}
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.
If you can't run claude mcp add yourself, tell the user how to add the server in their client, using Connecting AI tools.
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
- 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.
- Add the install button so readers can connect their own tools: Install button.
- Tune it: search ranking, Agent Skills, or your own search provider.