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

Variable	Required	Default	Description
NOCOBASE_API_TOKEN	Yes	—	NocoBase API token
NOCOBASE_URL	No	http://localhost:13000	NocoBase instance base URL

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

Tool	Description
list_collections	List all collections
get_collection	Get a collection by name

UI Schemas (Classic Pages)

Tool	Description
list_pages	List all UI schema nodes
get_page	Get full nested UI schema tree by UID
get_parent_schema	Get the parent schema of a node
create_page	Create a new root-level UI schema node
insert_new_schema	Create and insert a new UI schema node
insert_adjacent_schema	Insert a schema node relative to a target node
update_ui_schema	Patch an existing UI schema node
batch_patch_ui_schema	Patch multiple UI schema nodes in one request
remove_ui_schema	Remove a UI schema node and its descendants ⚠️
save_as_template	Save a UI schema node as a reusable block template

Desktop Routes / Navigation

Tool	Description
list_desktop_routes	List all desktop routes (pages, menus, groups, tabs)

Flow Models (flowPage blocks)

Tool	Description
get_flow_model	Get a flowPage block by UID
get_flow_model_by_parent	Get a flowPage block by parent ID and subKey
save_flow_model	Create or update a flowPage block
attach_flow_model	Attach a block to a flowPage container
move_flow_model	Move a block to a different position
duplicate_flow_model	Deep-copy a block and auto-attach it
destroy_flow_model	Delete a block and its children ⚠️

JS Blocks

Tool	Description
get_js_block	Get a JS block schema (classic page)
update_js_block	Update JS block code (classic page)
update_flow_js_block	Update JS block code inside a flowPage — use ctx.render() or JSX via ctx.libs.React

⚠️ 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.