# NocoBase CRM MCP

Read-only MCP server for remote agents that need customer, contact, follow-up, and CRM overview data from NocoBase.

The server calls the official `nb api resource list|get|query` commands. It does not expose create, update, destroy, or arbitrary command execution tools.

## Configure

This repository already includes a local `config.json` generated for the current CRM. To regenerate it from the example:

```bash
cp config.example.json config.json
```

The known CRM collection names in this environment are:

- customers: `t_nt3pjadelqi` (`客户`)
- contacts: `t_j77ftx1rf84` (`客户联系人`)
- followups: `t_07667a5evtr` (`跟进记录`)

The checked-in example config uses the confirmed mapping:

- customer owner: `kehu_followup_person` (`跟进人`)
- customer status/progress: `kh_progress` (`进度`)
- customer source: `f_225h6n6v654` (`客户来源`)
- contact-to-customer relation: `kehulianxiren_client`
- follow-up-to-customer relation: `gjjl_client`
- follow-up-to-contact relation: `gjjl_client_contacts`
- follow-up owner fields: `gjjl_followup_person` and `createdBy`
- follow-up date/content: `f_srysmjkwfq1` and `f_19iplxz0nds`

The default NocoBase CLI env is `nb-mcp`. Override it with:

```bash
export NOCOBASE_MCP_ENV=nb-mcp
export NOCOBASE_MCP_CONFIG=/home/nac/repo/nocobase-mcp/config.json
```

## Local stdio MCP

```bash
uv run nocobase-crm-mcp --config config.json
```

Exposed tools:

- `crm_health`
- `crm_schema`
- `crm_overview`
- `crm_filter_options`
- `resolve_owner`
- `list_customers`
- `get_customer`
- `list_contacts`
- `list_followups`

`crm_config_template` is hidden by default because it needs NocoBase data-modeling metadata permissions. Enable it only during configuration work:

```bash
NOCOBASE_MCP_ENABLE_CONFIG_TOOLS=1 uv run nocobase-crm-mcp --config config.json
```

The `owner` parameter on `crm_overview`, `list_customers`, and `list_followups` accepts a user's username, nickname, email, or English name. The server resolves that value through the `users` resource, then filters CRM relation fields by user id. If the value is missing or ambiguous, the tool returns a structured `error` object with candidate users instead of throwing an MCP error. Remote agents should call `resolve_owner` first when they are unsure which user the requester means.

Use `crm_filter_options` to discover status/source values and owner candidates before constructing filtered queries. List tools clamp `limit` to `1..100` and normalize negative offsets to `0`.

## Permissions

Runtime tools are read-only, but the role behind `nb-mcp` needs these read permissions:

- CRM collections: `t_nt3pjadelqi`, `t_j77ftx1rf84`, `t_07667a5evtr`
- user lookup collection: `users`, at least `id`, `username`, `nickname`, `email`, `f_yh_english_name`

`crm_schema(include_fields=true)` and the opt-in `crm_config_template` are configuration helpers. They use this read-only NocoBase data-modeling command:

```bash
nb api data-modeling collections fields list --collection-name <collection> --env nb-mcp --yes
```

Use a super-admin or configuration-capable role for this one-time discovery step. The remote Agent does not need data-modeling access after `config.json` is generated.

Do not grant write permissions such as collection apply/destroy, fields apply, or business data create/update/destroy for this MCP.

## Remote HTTP MCP

HTTP mode uses streamable HTTP with a separate bearer token for MCP access:

```bash
export NOCOBASE_MCP_TOKEN='<long-random-token>'
uv run nocobase-crm-mcp --transport streamable-http --config config.json
```

Default bind is `0.0.0.0:10087` with path `/mcp`.

Remote clients must send:

```http
Authorization: Bearer <long-random-token>
```

For a managed user-level systemd service:

```bash
bash scripts/mcp_service.sh start
```

The first `start` creates `.runtime/nocobase-crm-mcp.env` with a random bearer token automatically. Use `new-token` only when rotating the token later.

Show the saved URL/header/client config:

```bash
bash scripts/mcp_service.sh show-config
```

Check service state, saved paths, URL, and local HTTP probe:

```bash
bash scripts/mcp_service.sh status
```

Stop or uninstall:

```bash
bash scripts/mcp_service.sh stop
bash scripts/mcp_service.sh uninstall
```

The systemd unit references `.runtime/nocobase-crm-mcp.env`; it does not embed the bearer token. The env file is written with `0600` permissions and `.runtime/` is ignored.