• Customermates logo
    CustomermatesDocumentation
  • Introduction
  • Comparison
Getting Started
  • Quickstart
  • Core Concepts
  • From Pipedrive
Connect your AI
  • Connect Claude Code
  • Connect Claude Desktop
  • Connect Codex
  • Connect Cursor
  • Connect ChatGPT
Integrations
  • MCP
  • Webhooks
  • OpenAPI 3.1.0
  • N8N
Self-Hosting
  • Get Started
  • Architecture & Security
Reference
  • MCP Tool Catalog
  • Filter Syntax
  • API Keys
  • Go back
  1. Introduction
  2. Connect Claude Desktop

Connect Claude Desktop

Run Customermates as a Claude Desktop MCP server. One config file edit, restart, paste the setup prompt.

Claude Desktop's "Custom Connectors" UI is OAuth-only and doesn't accept static API headers, so we go through the config file with the mcp-remote shim. One JSON block, one restart.

If you use Claude Code (the CLI), see the Claude Code page — that path is a single terminal command.

1. Create an API key

In Customermates: Profile → API Keys → New key. Name it for the client (e.g. Claude Desktop). Copy the 64-character string immediately — it's shown once.

2. Edit the config file

Open Claude → Settings → Developer → Edit Config, or the file directly:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge this in, replacing YOUR_KEY:

{  "mcpServers": {    "customermates": {      "command": "npx",      "args": [        "-y",        "mcp-remote",        "https://customermates.com/api/v1/mcp",        "--header",        "x-api-key:YOUR_KEY"      ]    }  }}

Self-hosting? Swap the URL for your instance.

mcp-remote is a small shim that lets Claude Desktop talk to a remote HTTP MCP server using stdio under the hood. It downloads on first run via npx; you'll need Node 18+ on PATH.

3. Restart Claude Desktop

Fully quit (⌘Q on macOS, not just close the window) and reopen. Customermates appears in the tools panel with every CRM tool listed.

4. Paste this setup prompt as your first message

You are now connected to my Customermates CRM through MCP.## About CustomermatesCustomermates is an open-source CRM where the AI I already use keeps the data fresh. Five core entity types:- **Contacts**: people- **Organizations**: companies- **Deals**: sales opportunities with services and total value- **Services**: offerings a deal can include, each with a quantity- **Tasks**: todos assigned to team membersEntities link to each other. A contact belongs to one or more organizations and one or more deals. A deal has contacts, organizations, services (with quantities), and assignees. A task has assignees only. Every entity supports **custom columns** (user-defined fields) and **notes** (markdown).## Before you do anything, ask me for1. My name and role, so you can tailor your replies.2. What I usually do with my CRM, in one sentence.## Rules that keep my data safe- **Never pass `null` on relationship arrays** (`organizationIds`, `dealIds`, `contactIds`, `userIds`, `services`). Null wipes the relationship. Omit the field to keep existing links, pass `[]` to clear all, or use `link_entities` / `unlink_entities` to change specific ids.- **Prefer `link_entities` and `unlink_entities`** over `update_*` with relationship arrays. They merge instead of replacing.- **Custom fields are per-column merge**. Only the columnIds you include are changed; the rest are preserved. To clear one field pass `{ columnId, value: null }`.- **Use the correct per-type custom-column tool**. `update_plain_custom_column` for plain columns, `update_single_select_custom_column` for dropdowns, and so on. The server will tell you if you picked the wrong one.- **Before any create or update**, call `get_entity_configuration` for the entity to learn its custom column ids and filter syntax.- **Destructive actions need confirmation.** For `delete_*` or anything labelled IRREVERSIBLE, confirm with me first unless I explicitly said "just do it".## Suggested first moves1. Call `get_current_user` and `get_company` and tell me who and where I'm working.2. Call `count_entity` for contact, organization, deal, service, and task.3. Call `list_custom_columns` so we don't recreate fields that already exist.4. Ask me what I want to work on first.## Style- Prefer one short paragraph to a bullet wall, unless you're comparing options.- When you're about to run a destructive tool, name the tool and its arguments first.- When I ask "what's happening with X", use `search_all_entities` before guessing the entity type.Ready. Please ask me what I want to focus on.

The agent will orient itself and wait for direction.

Try your first real prompt

  • "Move the Acme deal to stage 'Won' and add a note that the contract was signed today."
  • "Pull the last ten contacts I created. Any without an email address?"
  • "Create a contact for Jane Doe at Initech, link it to the Initech org, and start a deal for 12 hours of consulting."

Troubleshooting

SymptomCauseFix
Tools panel is emptyClaude didn't reloadFully quit and reopen Claude Desktop
npx: command not foundNo Node on PATHInstall Node 18+ from nodejs.org
"Invalid API key"Wrong key lengthRegenerate in Profile → API Keys
Server rejects a relationship updateNull-wipe guard fired (this is a feature)Ask Claude to use link_entities / unlink_entities instead

Tips

  • Claude Desktop doesn't hot-reload MCP configs. Always quit and reopen after edits.
  • Use one API key per client if you want audit-log granularity.
  • For multiple Customermates accounts, add a second customermates-<tenant> block with that account's key.

Next

  • MCP tool catalog: every tool Claude can call.
  • Webhooks: subscribe other systems to CRM changes.
  • Connect Cursor: same server, different client.
1. Create an API key
2. Edit the config file
3. Restart Claude Desktop
4. Paste this setup prompt as your first message
Try your first real prompt
Troubleshooting
Tips
Next