← home

Run your CRM from Claude Code, Cursor, or Codex

The short version: jsoncrm mcp starts a stdio MCP server that exposes every CLI command as a tool — same names, same arguments, plus dry_run and apply booleans on every write. Point any MCP client at it and your agent can search, score, promote, and validate the pipeline, with previews before anything lands on disk.

What you need

A CRM directory with a .crm.json (or the marketing-CRM defaults — see the quick start)
The server: pip install "jsoncrm[mcp]" — or zero-install with uvx --from "jsoncrm[mcp]" jsoncrm mcp
The absolute path to your .crm.json (MCP clients don't inherit your shell's working directory)

How the tools map to the CLI

There is nothing to relearn. search, stats, list, add, update, delete, promote, demote, validate, deduplicate, merge, backup — every canonical command is a tool with the same name. Two MCP-specific conveniences:

item_json accepts a native object — no string-encoded JSON
Every write tool takes dry_run and apply booleans, mutually exclusive, matching the CLI's --dry-run / --apply

Claude Code

claude mcp add --transport stdio jsoncrm -- \
  jsoncrm --config /absolute/path/to/.crm.json mcp

Claude Desktop

{
  "mcpServers": {
    "jsoncrm": {
      "command": "jsoncrm",
      "args": ["--config", "/absolute/path/to/.crm.json", "mcp"]
    }
  }
}

In claude_desktop_config.json (Settings → Developer).

Cursor

// .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
  "mcpServers": {
    "jsoncrm": {
      "command": "jsoncrm",
      "args": ["--config", "/absolute/path/to/.crm.json", "mcp"]
    }
  }
}

Or add it under Settings → MCP.

Codex

# ~/.codex/config.toml
[mcp_servers.jsoncrm]
command = "jsoncrm"
args = ["--config", "/absolute/path/to/.crm.json", "mcp"]

Verify it works

Ask your agent:

"list the jsoncrm tools, then run stats on my CRM"

You should see the tool list (21 tools) and the per-stage counts from your pipeline files. If the agent can't find the tools, the config path is the usual suspect — it must be absolute.

The dry-run discipline

This is the part that makes agent-written CRM changes reviewable. Ask for a preview, read the JSON, then apply:

"promote everyone at ⭐⭐⭐⭐ or above to prospects — dry run first, show me the records"

The agent calls promote with dry_run: true for each record; nothing is written. Every result includes the prospective record. When it looks right:

"looks good — apply all of them, then commit with a message summarizing the promotions"

The write lands, git diff shows exactly what changed, and the commit becomes the audit entry. The same preview-then-apply loop works for add, update, delete, and demote.

Good first prompts

"search my pipeline for anyone at TestPharma"
"show me the top 5 unscored leads, then score them with a one-line rationale each — dry run"
"validate all pipeline files and report anything suspicious"
"who was added to the CRM this week?"

More recipes: the agent cookbook.

Troubleshooting

Tools don't appear: check the client's MCP log; confirm jsoncrm mcp runs in a terminal
"no such file" errors: the config path isn't absolute, or the client's shell can't find jsoncrm — use the full path to the executable (e.g. /Users/you/.local/bin/jsoncrm)
Empty pipeline: the server reads the CRM directory your .crm.json lives in — if you point it at the wrong directory, you get empty arrays, not an error
Agent hand-edits JSON anyway: install the agent skill so it knows the house rules (never hand-edit when a tool exists, dry-run first, commit after writes)

Your CRM is now an agent tool.

Same files, same git history, now with 21 tools your agent can call.

Read the cookbook ★ GitHub