nocobase-ui MCP

MCP server exposing the NocoBase flow-surfaces API as MCP tools. Enables programmatic UI authoring — pages, blocks, templates, navigation — without a local nb CLI installation.

Installation

{
  "nocobase-ui": {
    "command": "npx",
    "args": ["-y", "@minhjacode/[email protected]"],
    "env": {
      "NOCOBASE_API_URL": "https://your-instance.example.com",
      "NOCOBASE_UI_TOKEN": "your-token"
    }
  }
}

Add this to your MCP client config (Claude Desktop, Claude Code, or any MCP-compatible client).

Configuration

Two environment variables are required:

NOCOBASE_API_URL — NocoBase instance API base URL, e.g. https://your-instance.example.com

NOCOBASE_UI_TOKEN — API token with the nb-ui role (requires Configure Interface + Data Sources: view permissions). Create it in NocoBase UI → Settings → API Keys.

Tools

Inspect

• health_check — connectivity test
• list_routes — desktop navigation routes with id/title/icon/pageSchemaUid
• get_surface — UISchema skeleton for a page, tab, or block
• describe_surface — richer structural readback with collection/field metadata
• catalog — available block types, fields, and actions at a target node
• get_reaction_meta — read-only inspection of rules and reactions on a node
• list_templates — saved block templates
• get_template — single template by UID

Whole-page write

• apply_blueprint — create or replace a whole page via blueprint
• destroy_page — delete a page

Localized write

• compose — add blocks to an existing page or tab
• add_block — add a single block to a target surface
• add_field — add fields to an existing block (FilterForm, Table, Form, Details)
• configure — update settings on an existing block, field, or action
• set_rules — set valueRules, fieldLinkageRules, blockLinkageRules, or actionLinkageRules
• patch_schema — raw stepParams patch (escape hatch when configure is blocked)
• save_template — save a block as a reusable template

Navigation

• create_menu — create a navigation menu entry
• update_menu — update menu title or icon
• destroy_menu — delete a navigation menu entry

Tabs and nodes

• add_tab / update_tab / remove_tab — tab lifecycle
• remove_node — delete a block, field, or action node
• move_node — reorder a node within its container

Limitations

get_surface and list_routes default to mode: "structure", which returns a compact skeleton instead of the raw NocoBase UISchema tree. Popup form field UIDs are not visible in structure mode — use mode: "full" with a specific block UID to inspect popup content.

New tools (add_field, set_rules, get_reaction_meta, patch_schema) depend on server-side endpoints that may not be available in all NocoBase versions. These wrap flowSurfaces:addField, flowSurfaces:setRules, flowSurfaces:getReactionMeta, and uiSchemaNodes:patch respectively.

Baseline

Built against NocoBase 2.1.0-beta.40-full. The tool parameter schemas are derived from the nb CLI commands.json OpenAPI snapshot. When upgrading NocoBase, re-validate the flow-surfaces endpoints against the new commands.json.

Relationship to nb CLI

The nb CLI wraps the same flowSurfaces:* HTTP endpoints with no additional client-side logic. Validation errors come from the NocoBase server as errors[] in the response — this MCP passes them through unchanged.