129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# 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.
|