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:

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:

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

Local stdio MCP

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:

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:

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:

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:

Authorization: Bearer <long-random-token>

For a managed user-level systemd service:

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 scripts/mcp_service.sh show-config

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

bash scripts/mcp_service.sh status

Stop or uninstall:

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.