# 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+](https://img.shields.io/badge/python-3.11+-blue.svg)
![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)
![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)

## 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

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

### 2. Seed demo data

```bash
python -m mcp_server_crm.seed
```

### 3. Run with Claude Desktop

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

```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)

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

### 5. Test with MCP Inspector

```bash
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

```bash
# 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