mcp-server-crm

mcp-server-crm

Freelancer Client Pipeline Tracker — An MCP Server that gives Claude (or any MCP-compatible LLM) tools to manage leads, track pipeline stages, log interactions, and generate reports.

!Python 3.11+ !MCP !License: MIT

Architecture

┌─────────────────────────────────────────────────┐
│                  Claude Desktop                  │
│            (or any MCP-compatible LLM)           │
└─────────────────┬───────────────────────────────┘
                  │ MCP Protocol (stdio)
                  ▼
┌─────────────────────────────────────────────────┐
│              mcp-server-crm                      │
│                                                  │
│  ┌──────────┐    ┌──────────┐                   │
│  │ server.py│    │  api.py  │                   │
│  │ (MCP)    │    │ (FastAPI)│                   │
│  └────┬─────┘    └────┬─────┘                   │
│       └───────┬───────┘                          │
│               ▼                                  │
│        ┌────────────┐                            │
│        │ queries.py │  (shared business logic)   │
│        └──────┬─────┘                            │
│               ▼                                  │
│        ┌────────────┐                            │
│        │   db.py    │  (SQLite / PostgreSQL)     │
│        └────────────┘                            │
└─────────────────────────────────────────────────┘

Key design: Both the MCP server and FastAPI REST API share the same queries.py business logic — zero duplication, guaranteed behavioral parity.

Features

| Tool | Description | |------|-------------| | search_leads | Search leads by status, source, and budget range | | get_lead | Get full details for a single lead | | create_lead | Add a new lead at the "prospect" stage | | update_lead | Update lead information (partial updates) | | update_stage | Move a lead through the pipeline with history tracking | | get_reminders | Find leads with past-due follow-up dates | | get_pipeline_report | Win rate, revenue stats, stage breakdown | | flag_overdue | Red-flag leads overdue by 3+ days | | add_activity | Log emails, calls, meetings, proposals |

Pipeline Stages

prospect → contacted → proposal_sent → qualified → negotiation → closed_won
                                                                → closed_lost

Quick Start

1. Install

git clone https://github.com/Aniketsingh12/mcp-server-crm.git
cd mcp-server-crm
pip install -e ".[dev]"

2. Seed demo data

python -m mcp_server_crm.seed

3. Run with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "crm": {
      "command": "python",
      "args": ["-m", "mcp_server_crm.server"]
    }
  }
}

Then ask Claude things like:

• "Show me all leads from LinkedIn with budget over $5000"
• "Move Nexus Financial to the negotiation stage"
• "Which leads have overdue follow-ups?"
• "Give me a pipeline report"

4. Run the REST API (optional)

python scripts/run_both.py
# Open http://127.0.0.1:8000/docs for Swagger UI

5. Test with MCP Inspector

mcp dev src/mcp_server_crm/server.py

REST API Reference

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | GET | /leads | Search leads (query params: status, source, min_budget, max_budget) | | GET | /leads/{id} | Get a lead | | POST | /leads | Create a lead | | PATCH | /leads/{id} | Update a lead | | PATCH | /leads/{id}/stage | Change pipeline stage | | DELETE | /leads/{id} | Delete a lead | | GET | /leads/{id}/activities | List lead activities | | POST | /leads/{id}/activities | Log an activity | | GET | /reminders | Get follow-up reminders | | GET | /overdue | Get critical overdue leads | | GET | /reports/pipeline | Full pipeline report |

Development

# Run tests
pytest -v

# Run API with auto-reload
uvicorn mcp_server_crm.api:app --reload

PostgreSQL Migration Path

The SQLite database can be swapped to Supabase/PostgreSQL by:

1. Adding asyncpg to dependencies
2. Updating db.py connection to use DATABASE_URL env var
3. Adjusting SQL placeholders (? → $1, $2)

The queries.py function signatures stay identical — only internal SQL changes.

Tech Stack

• Python 3.11 — Runtime
• MCP SDK (FastMCP) — Model Context Protocol server
• FastAPI — REST API
• SQLite — Zero-config database (swap to PostgreSQL for production)
• Pydantic — Data validation and serialization

License

MIT