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.
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.
Open Claude → Settings → Developer → Edit Config, or the file directly:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonMerge 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.
Fully quit (⌘Q on macOS, not just close the window) and reopen. Customermates appears in the tools panel with every CRM tool listed.
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.
| Symptom | Cause | Fix |
|---|---|---|
| Tools panel is empty | Claude didn't reload | Fully quit and reopen Claude Desktop |
npx: command not found | No Node on PATH | Install Node 18+ from nodejs.org |
| "Invalid API key" | Wrong key length | Regenerate in Profile → API Keys |
| Server rejects a relationship update | Null-wipe guard fired (this is a feature) | Ask Claude to use link_entities / unlink_entities instead |
customermates-<tenant> block with that account's key.