🧩 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.

📸 Screenshots

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

CRM server tools:

Analytics server tools:

Related MCP server: MCP Toolkit Server

📖 Table of Contents

• Screenshots

• Why this project

• Architecture

• Features

• Tech Stack

• MCP Tools Reference

• Getting Started

• Project Structure

• 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

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

🔧 MCP Tools Reference

crm server

crm-analytics server

🚀 Getting Started

Prerequisites

• Python 3.13+

• An OpenRouter 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

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

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

3. Initialize the database

python -m database.schema

4. Run it

Option A — standalone chat agent:

python -m client.chat

Option B — plug into Claude Code:

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