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

1. Clone and install dependencies

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

2. Configure Claude Code (or any MCP client)

Add to ~/.claude/mcp.json (Claude Code global MCP config):

{
  "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 where you cloned the repo (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 />);

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.