MCP Server for SuiteCRM
A Model Context Protocol server that lets AI assistants (GitHub Copilot agent mode in VS Code, Claude Code, Claude Desktop and other MCP clients) work with SuiteCRM 7 through its v4_1 REST API: discover modules and fields, search and read records, follow relationships, and find duplicate accounts. Creating or updating single records is available when you switch it on.
It never deletes or merges records and never changes relationships.
Not affiliated with or endorsed by SalesAgility. "SuiteCRM" is a trademark of its owner.
| Tool |
What it does |
suitecrm_list_modules |
Modules the API user can see, with access flags |
suitecrm_get_module_fields |
Fields (types, labels, dropdown options) and relationship links |
suitecrm_search_records |
Records matching structured filters (escaped for you), with paging |
suitecrm_count_records |
Count for the same filters |
suitecrm_get_record |
One record by id |
suitecrm_find_by_email |
Accounts/Contacts/Leads linked to an email address |
suitecrm_unified_search |
SuiteCRM's global search |
suitecrm_get_related |
Records related through a link (e.g. an account's contacts) |
suitecrm_relationship_counts |
How many related records hang off one record, per link |
suitecrm_compare_records |
Field-by-field differences between 2-10 records |
suitecrm_find_duplicate_accounts |
Accounts sharing the same account number and normalised name |
suitecrm_api_read |
Any other read-only v4_1 method |
Only offered when writes are enabled:
| Tool |
What it does |
suitecrm_save_record |
Create a record, or update one (only changed fields are sent), then read back and verify |
Writes default to dry_run: true. Only fields that exist on the module are accepted; id, deleted and audit fields are refused.
Things worth knowing
- Field names differ between installations, and custom fields do not always end in
_c. The server checks filters against the module's real field list.
- Dropdown fields store keys;
suitecrm_get_module_fields shows the labels.
- Email is not a plain column;
suitecrm_find_by_email goes through SuiteCRM's email tables.
- The duplicate finder needs the Accounts field that holds your customer number. Matching levels:
strict (case and spaces), loose (also punctuation, HTML entities, &/and, "closed" markers), core (also legal suffixes such as Inc or LLC). Merging stays in SuiteCRM's own merge screen.
Use in VS Code
- Install the extension.
- Run SuiteCRM MCP: Add or Edit Profile. Enter the SuiteCRM URL, an optional label (for example
staging or production), the optional account number field, whether writes are allowed, then the username and password.
- In Copilot Chat agent mode the server appears as SuiteCRM (or SuiteCRM (profile)).
Use a dedicated API user with only the access the assistant needs. Credentials live in VS Code Secret Storage and are tied to the profile's URL. The server runs on VS Code's own Node.js runtime.
| Setting |
Scope |
Purpose |
suitecrmMcp.profiles |
user |
name, url, environmentLabel, accountNumberField, allowWrites |
suitecrmMcp.nodePath |
machine |
Use a different Node.js executable (normally leave empty) |
Use with other MCP clients
{
"mcpServers": {
"suitecrm": {
"command": "node",
"args": ["/path/to/suitecrm-mcp/dist/server.js"],
"env": {
"SUITECRM_URL": "https://crm.example.com",
"SUITECRM_USERNAME": "${SUITECRM_USERNAME}",
"SUITECRM_PASSWORD": "${SUITECRM_PASSWORD}",
"SUITECRM_ALLOW_WRITES": "false"
}
}
}
}
| Variable |
Default |
Purpose |
SUITECRM_URL |
(required) |
Site URL (/service/v4_1/rest.php is added). Must be https except for localhost |
SUITECRM_USERNAME, SUITECRM_PASSWORD |
(required) |
API user. The password may also be given as its MD5 hash |
SUITECRM_ENVIRONMENT_LABEL |
host name |
Shown in write previews |
SUITECRM_ACCOUNT_NUMBER_FIELD |
|
Accounts field for the duplicate finder |
SUITECRM_ALLOW_WRITES |
false |
Offer suitecrm_save_record |
SUITECRM_MAX_RESULTS |
200 |
Cap per request |
SUITECRM_APPLICATION_NAME |
suitecrm-mcp |
Shown in SuiteCRM's login records |
SUITECRM_TIMEOUT_SECONDS |
30 |
Per-request timeout |
SUITECRM_MAX_CONCURRENCY |
4 |
Parallel requests |
SUITECRM_LOG_LEVEL |
info |
Logs go to stderr |
Note: the v4_1 API logs in with the MD5 hash of the password, so anyone who obtains that hash can log in. Treat it like the password.
Privacy and data handling
- The server talks only to the SuiteCRM URL you configure. No telemetry.
- Records contain personal data and go to the AI assistant you use.
- Passwords, their hashes and session ids are masked in logs, errors and results.
Development
npm ci
npm test # offline tests; a fake fetch blocks any real network call
npm run build
npm run package # runs the NDA check, type check and production build first
License
MIT
