nocobase-mcp-server

An MCP (Model Context Protocol) server for NocoBase, enabling AI assistants like Claude to interact with your NocoBase instance — read collections, manage UI schemas, build flowPage blocks, and run dynamic API operations via OpenAPI.

Features

• 24 hand-crafted tools covering collections, UI schemas, desktop routes, flow models, and JS blocks
• Dynamic tools auto-generated from your NocoBase's OpenAPI/Swagger spec (requires API documentation plugin)
• Works with NocoBase v2.x (tested on 2.0.17-full)

Requirements

• Node.js 18+
• A running NocoBase instance
• A NocoBase API token (root or sufficient permissions)

Installation

Option A — via npm (recommended)

npm install -g @reroet/nocobase-mcp-server

Then add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "nocobase": {
      "type": "stdio",
      "command": "nocobase-mcp-server",
      "env": {
        "NOCOBASE_URL": "http://localhost:13000",
        "NOCOBASE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Or use npx without installing globally:

{
  "mcpServers": {
    "nocobase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@reroet/nocobase-mcp-server"],
      "env": {
        "NOCOBASE_URL": "http://localhost:13000",
        "NOCOBASE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Option B — from source

git clone https://github.com/puguhsudarma/nocobase-mcp-server.git
cd nocobase-mcp-server
pnpm install

Then add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "nocobase": {
      "type": "stdio",
      "command": "/absolute/path/to/nocobase-mcp-server/node_modules/.bin/tsx",
      "args": ["/absolute/path/to/nocobase-mcp-server/src/index.ts"],
      "env": {
        "NOCOBASE_URL": "http://localhost:13000",
        "NOCOBASE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Replace /absolute/path/to/nocobase-mcp-server with the actual path (e.g. /Users/yourname/Projects/nocobase-mcp-server).

Environment Variables

Getting an API Token

1. In NocoBase UI: Settings → Plugins → enable the API keys plugin
2. Go to Settings → API keys → Add API key
3. Copy the generated token

Enabling Dynamic Tools (optional)

Enable the API documentation plugin in NocoBase (Settings → Plugins). Once active, the server will automatically load all additional API endpoints as tools on startup.

Tools Reference

Collections

UI Schemas (Classic Pages)

Desktop Routes / Navigation

Flow Models (flowPage blocks)

JS Blocks

⚠️ Destructive operations cannot be undone.

JS Block Sandbox

flowPage JS blocks run in NocoBase's sandbox. Available APIs:

// Render HTML
ctx.render(`<h1>Hello</h1>`);

// Render JSX with React + Ant Design
const { React, antd } = ctx.libs;
const { useState } = React;
const { Table, Tag } = antd;

function MyComponent() {
  const [tab, setTab] = useState("a");
  return <div>...</div>;
}

ctx.render(<MyComponent />);

Example Prompts

How to get UIDs:

• Block UID — right-click any block in NocoBase UI → Copy UID (e.g. add17a3cf3f)
• Page UID — visible in the browser URL when you open a page (e.g. http://localhost:13000/page/96acpujiwc6 → UID is 96acpujiwc6)

Without Figma MCP

List all collections in my NocoBase, then create a JS block on flowPage "<your-page-uid>"
that shows a summary dashboard with total records from the "users" collection.

Get the flowPage with UID "<your-page-uid>", add a new JS block below the existing ones
(the grid block UID is "<your-grid-uid>"), and implement a tabbed table showing data
from the "orders" and "products" collections.

Show me all desktop routes, then fetch the UI schema tree of the first page
and explain its block structure.

With Figma MCP

Here's my Figma design: https://www.figma.com/board/XXXXXXXXXXXXXXXX/MyApp?node-id=8273-xxxx
Implement it as a JS block on flowPage "<your-page-uid>" (grid UID: "<your-grid-uid>").
Use React + Ant Design from ctx.libs. Use dummy data for now.

Fetch the Figma design at the link above, then create a new JS block on my NocoBase
flowPage and implement the tabs component with the exact columns from the Figma table.
The block UID I want to update is "<your-block-uid>".

Contributing

Contributions are welcome! To add a new tool:

1. Fork the repo and create a feature branch
2. Add your tool in src/index.ts using server.registerTool()
3. Follow the existing pattern — use nocoFetch() for API calls and ok() to format responses
4. Update the tool list in README.md
5. Open a pull request

For bug reports or feature requests, open an issue on GitHub.

License

MIT — see LICENSE for details.