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.