MCP Server NocoBase Remote

Remote MCP server for NocoBase instances with multi-instance support. Designed to be deployed on Easypanel or any container platform.

Features

• Streamable HTTP transport - Remote MCP access via HTTP
• Multi-instance support - Connect to multiple NocoBase instances from a single server
• Easypanel ready - Docker image with health checks
• API Key authentication - Secure connection to NocoBase instances
• Auto-generated tools - Converts NocoBase OpenAPI spec into MCP tools automatically

Quick Start

Local Development

npm install
cp .env.example .env
# Edit .env with your NocoBase URL and token
npm run dev

Build and Run

npm run build
npm start

Configuration

Environment Variables

Variable	Required	Description
PORT	No	Server port (default: 3000)
NOCOBASE_URL	Yes*	URL of the NocoBase instance
NOCOBASE_TOKEN	Yes*	API Key for the NocoBase instance
INSTANCE_NAME	No	Name for the default instance (default: default)
INSTANCE_PACKAGES	No	Override MCP packages for default instance
MCP_PACKAGES	No	Comma-separated list of packages to expose
INSTANCES	No	JSON array of additional instances

*Required if INSTANCES is not set

Single Instance

NOCOBASE_URL=http://nocobase:13000
NOCOBASE_TOKEN=your-api-key

Multiple Instances

NOCOBASE_URL=http://nocobase-main:13000
NOCOBASE_TOKEN=main-key

INSTANCES=[{"name":"crm","url":"http://nocobase-crm:13000","token":"crm-key"},{"name":"erp","url":"http://nocobase-erp:13000","token":"erp-key"}]

Docker / Easypanel

Build Image

docker build -t mcp-server-nocobase-remote .

Run Container

docker run -d \
  -p 3000:3000 \
  -e NOCOBASE_URL=http://nocobase:13000 \
  -e NOCOBASE_TOKEN=your-api-key \
  --name mcp-nocobase \
  mcp-server-nocobase-remote

Easypanel Deployment

1. Create a new service from Dockerfile
2. Point to this repository
3. Add environment variables:
   • NOCOBASE_URL - URL of your NocoBase instance
   • NOCOBASE_TOKEN - API Key from NocoBase
4. Deploy

Endpoints

Endpoint	Method	Description
/mcp	POST/GET/DELETE	MCP streamable HTTP endpoint
/health	GET	Health check
/instances	GET	List configured instances

Client Configuration

OpenCode

{
  "mcp": {
    "nocobase": {
      "type": "remote",
      "url": "http://your-server:3000/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Code

claude mcp add --transport http nocobase http://your-server:3000/mcp

Codex CLI

codex mcp add nocobase --url http://your-server:3000/mcp

How It Works

1. Server loads NocoBase instances from environment variables
2. Each instance connects to NocoBase and fetches the OpenAPI/Swagger spec
3. openapi2mcptools converts the API spec into MCP tools
4. Tools are prefixed with instance name (e.g., crm_collections_list)
5. Clients connect via streamable HTTP to /mcp endpoint
6. MCP tools allow full CRUD operations on NocoBase collections

NocoBase Setup

1. Enable the NocoBase MCP Server plugin
2. Enable the API Keys plugin
3. Create an API key in Settings -> API keys
4. Use the URL and token in this server's configuration

License

MIT