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

*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

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