# 🧩 Local MCP CRM

> A local-first CRM built on the **Model Context Protocol (MCP)** — customer & project
> management exposed as MCP tools, driven by either a custom LlamaIndex ReAct agent
> or directly from **Claude Code**.

<p>
  <img alt="python" src="https://img.shields.io/badge/Python-3.13-3776AB?logo=python&logoColor=white">
  <img alt="mcp" src="https://img.shields.io/badge/Protocol-MCP-6f42c1">
  <img alt="sqlite" src="https://img.shields.io/badge/Database-SQLite-003B57?logo=sqlite&logoColor=white">
  <img alt="llamaindex" src="https://img.shields.io/badge/Agent-LlamaIndex-black">
  <img alt="status" src="https://img.shields.io/badge/status-active-success">
</p>

## 📸 Screenshots

**Both servers connected inside Claude Code (VS Code extension):**

![MCP servers overview](assets/mcp-servers-overview.png)

**CRM server tools:**

![CRM server tools](assets/crm-server-tools.png)

**Analytics server tools:**

![Analytics server tools](assets/crm-analytics-tools.png)

## 📖 Table of Contents

- [Screenshots](#-screenshots)
- [Why this project](#-why-this-project)
- [Architecture](#-architecture)
- [Features](#-features)
- [Tech Stack](#-tech-stack)
- [MCP Tools Reference](#-mcp-tools-reference)
- [Getting Started](#-getting-started)
- [Project Structure](#-project-structure)
- [Roadmap](#-roadmap)

## 🎯 Why this project

This is a small, deliberately layered CRM that doubles as a hands-on demonstration of the
**Model Context Protocol** — the emerging standard for connecting LLMs to tools and data.
It ships **two independent MCP servers** (`crm` and `crm-analytics`), each exposing a clean
set of tools over stdio, and **two different clients** talking to them:

1. A **custom agent** (`client/`) — a LlamaIndex `ReActAgent` wired to a free OpenRouter
   model, with its own MCP client, tool-schema translation, and a simple multi-turn
   "collect missing fields" workflow.
2. **Claude Code itself** — via `.mcp.json`, the same servers plug straight into Claude
   Code (or any other MCP-compatible client) with zero extra glue code.

The point isn't the CRM domain (customers/projects are intentionally simple) — it's the
architecture underneath: a clean **repository → service → MCP tool → server** pipeline that
keeps business logic, data access, and protocol plumbing separate and independently
testable.

## 🏗️ Architecture

```mermaid
flowchart LR
    subgraph Clients
        A["Custom ReAct Agent\n(client/chat.py)"]
        B["Claude Code /\nany MCP client"]
    end

    subgraph Servers["MCP Servers (stdio)"]
        C["CRM Server\nservers/crm_server"]
        D["Analytics Server\nservers/analytics_server"]
    end

    subgraph Domain["Domain Layer"]
        E["Services\n(validation & business rules)"]
        F["Repositories\n(data access)"]
    end

    G[("SQLite\ncrm.db")]

    A -- MCP --> C
    A -- MCP --> D
    B -- MCP --> C
    B -- MCP --> D
    C --> E
    D --> E
    E --> F
    F --> G
```

Each layer has one job:

- **Repositories** — raw SQL against SQLite, nothing else.
- **Services** — validation and business rules (e.g. "can't create a project for a
  customer that doesn't exist").
- **MCP tools** — translate service calls into the `{success, data/error, message}`
  shape every tool returns.
- **Servers** — register those tools on a `FastMCP` instance and speak stdio.

## ✨ Features

- ✅ Customer CRUD — create, look up by name or ID
- ✅ Project lifecycle — create, update status (`Active` / `Delayed` / `Completed`), list by customer
- ✅ Analytics — aggregate stats, delayed-project tracking, per-customer reports
- ✅ Two independent MCP servers, each with a focused tool surface
- ✅ Works as a drop-in MCP integration for **Claude Code** — no adapter code needed
- ✅ Standalone chat agent with tool-calling via LlamaIndex `ReActAgent`
- ✅ Layered architecture (repository / service / tool / server) — each piece testable in isolation

## 🛠️ Tech Stack

| Layer | Technology |
|---|---|
| Protocol | [Model Context Protocol](https://modelcontextprotocol.io) (`mcp` Python SDK, `FastMCP`) |
| Agent / LLM orchestration | [LlamaIndex](https://www.llamaindex.ai/) `ReActAgent` |
| LLM | OpenRouter (free-tier model) / LM Studio (local, optional) |
| Database | SQLite |
| Language | Python 3.13 |

## 🔧 MCP Tools Reference

### `crm` server

| Tool | Description |
|---|---|
| `create_customer` | Create a customer (`name`, `email`, `company`) |
| `get_customer_by_name` | Look up a customer by name |
| `get_customer_by_id` | Look up a customer by ID |
| `create_project` | Create a project under a customer |
| `update_project_status` | Update a project's status |
| `get_projects_by_customer` | List all projects for a customer |

### `crm-analytics` server

| Tool | Description |
|---|---|
| `get_customer_statistics` | Aggregate counts — total customers, total projects, delayed projects |
| `get_delayed_projects` | List every project currently marked `Delayed` |
| `generate_project_report` | Full project report for a single customer |

## 🚀 Getting Started

### Prerequisites

- Python 3.13+
- An [OpenRouter](https://openrouter.ai) API key (free tier works) — only needed for the
  standalone chat agent, **not** for using the servers from Claude Code

### 1. Clone & set up a virtual environment

```bash
git clone <your-repo-url>
cd local-mcp-crm

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
```

### 2. Configure environment variables

```bash
cp .env.example .env
# then fill in OPENROUTER_API_KEY (and LM Studio settings, if you use them)
```

### 3. Initialize the database

```bash
python -m database.schema
```

### 4. Run it

**Option A — standalone chat agent:**

```bash
python -m client.chat
```

**Option B — plug into Claude Code:**

```bash
cp .mcp.json.example .mcp.json
# replace <ABSOLUTE_PATH_TO_PROJECT> with this project's absolute path
# (on macOS/Linux, point "command" at .venv/bin/python instead of .venv/Scripts/python.exe)
```

Reload Claude Code / run `/mcp` — you should see `crm` and `crm-analytics` connected, as
in the screenshots above.

## 📂 Project Structure

```
local-mcp-crm/
├── servers/
│   ├── crm_server/          # MCP server: customers & projects
│   └── analytics_server/    # MCP server: aggregate analytics
├── services/                # Business rules & validation
├── repositories/            # SQLite data access
├── database/                # Schema + connection helper
├── client/                  # Standalone LlamaIndex ReAct agent
├── models/                  # (reserved for typed domain models)
├── tests/                   # Manual verification scripts
├── .env.example
├── .mcp.json.example
└── requirements.txt
```

## 🗺️ Roadmap

- [ ] Convert the manual scripts in `tests/` into a real `pytest` suite
- [ ] Pydantic-based input validation at the MCP tool boundary
- [ ] Package `crm_server` and `analytics_server` into a single MCP server with resource-based tool grouping
- [ ] CI (lint + tests) on push

---

<p align="center">Built as a hands-on exploration of the Model Context Protocol.</p>