Demo CRM MCP Server

Let an AI assistant work a sales pipeline safely: search leads, catch duplicates before they are created, and route each lead to the right salesperson.

This is a Model Context Protocol (MCP) server written in Python. Connect it to an MCP client such as Claude Desktop and you can manage a CRM in plain English:

"Show me today's new leads in Victoria, check them for duplicates, and suggest who should own each one."

It is based on the kind of lead automation I build in production (duplicate detection, territory-based allocation, audit trails), rebuilt from scratch as an open demo with 100% fictional data.

Why this project

AI assistants are most useful when they can act on real business systems, but giving them write access to a CRM is risky. This server shows how to do it responsibly:

Related MCP server: MCP Suite CRM

Architecture

flowchart LR
    U[You] -->|plain English| C[MCP client<br/>e.g. Claude Desktop]
    C <-->|MCP over stdio| S[crm-mcp server]
    S --> T1[Read tools<br/>search · get · duplicates<br/>recommend · summary]
    S --> T2[Write tools<br/>create · status · note · assign]
    T2 --> G{Guards<br/>validation · duplicate check<br/>read-only mode}
    T1 --> DB[(SQLite demo CRM)]
    G --> DB
    G --> A[(Audit log)]

What the AI can do

Tools

Resources: crm://schema (fields, statuses, duplicate rules) and crm://audit-log (recent changes).

Prompt: daily_triage, a ready-made workflow that reviews new leads, flags duplicates and proposes assignments, then asks you to confirm before changing anything.

Duplicate detection

Phone numbers and emails are normalised first, so +61 491 570 156, 0491-570-156 and (04) 9157 0156 are treated as the same number.

A lead is never matched against itself. Example output:

{
  "lead_id": 38,
  "possible_duplicates": [
    {
      "lead_id": 6,
      "name": "Jack Khan",
      "confidence": "high",
      "reasons": [
        "Same phone number (after removing formatting)",
        "Same full name and postcode"
      ]
    }
  ]
}

And when the AI tries to create a lead that already exists:

{
  "created": false,
  "message": "Not created: this looks like an existing lead. Review the matches, then call create_lead again with allow_duplicate=true if it really is a new person.",
  "possible_duplicates": [
    { "lead_id": 1, "name": "Ruby Singh", "confidence": "high", "reasons": ["Same email address"] }
  ]
}

Quick start

Requires Python 3.10 or later.

git clone https://github.com/hayathi06/crm-mcp-server.git
cd crm-mcp-server
python -m venv .venv
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest            # run the tests

On first run the server creates demo_crm.db with 40 fictional leads, 6 salespeople and four planted duplicates for the detector to find.

Connect to Claude Desktop

In Claude Desktop, open Settings → Developer → Edit Config and add the server to claude_desktop_config.json. Use the full path to the Python inside your virtual environment:

{
  "mcpServers": {
    "demo-crm": {
      "command": "C:\\path\\to\\crm-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["-m", "crm_mcp"],
      "env": {
        "CRM_MCP_DB": "C:\\path\\to\\crm-mcp-server\\demo_crm.db",
        "CRM_MCP_READ_ONLY": "0"
      }
    }
  }
}

On macOS or Linux the command is /path/to/crm-mcp-server/.venv/bin/python. Restart Claude Desktop and the CRM tools appear.

Try these prompts

• "Give me a pipeline summary for NSW."

• "Find leads that are probably duplicates and explain why."

• "Add a new lead: Ruby Singh, RUBY.SINGH0@example.com, Perth 6000." (watch the duplicate check block it)

• "Which new leads have no owner? Recommend a salesperson for each and assign them once I confirm."

• "Run the daily triage for VIC."

Configuration

Project structure

src/crm_mcp/
  server.py       MCP tools, resources and prompt
  crm.py          CRM logic, validation, audit log, demo data
  duplicates.py   Normalisation and duplicate rules
tests/
  test_crm.py     Unit tests for the CRM logic
  test_server.py  End-to-end tests over a real MCP stdio session

About the data

Everything is invented. Names are made up, emails use the reserved example.com domain, and phone numbers come from the ranges the Australian Communications and Media Authority reserves for fiction.

Author

Noor Hayathi Jamal Mohammed, AI Automation Engineer, Melbourne Portfolio · LinkedIn

MIT licensed.