# 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

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

### Build and Run

```bash
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

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

### Multiple Instances

```env
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

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

### Run Container

```bash
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

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

### Claude Code

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

### Codex CLI

```bash
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