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.

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