<div align="center">

# Relatio, a Lightweight Personalizable CRM

### A tiny, self-hosted CRM with a built-in **MCP connector**, so your AI can run it for you.
**Works with Claude, ChatGPT, Gemini, or any MCP-compatible assistant.**

<!-- Swap in your own repo links once published -->
![License: MIT](https://img.shields.io/badge/license-MIT-0ea5e9)
![Node](https://img.shields.io/badge/node-%E2%89%A520-0369a1)
![MCP](https://img.shields.io/badge/MCP-connector%20built--in-16a34a)
![No build step](https://img.shields.io/badge/build%20step-none-64748b)

<br>

<img src="docs/images/demo.gif" alt="Relatio CRM in action: logging an activity, drafting an email reply, and testing the MCP connector" width="850">

<sub>Log a call, draft a reply, then check the AI connector. Same data your assistant reads and writes over MCP.</sub>

</div>

---

## What is this?

**Relatio** is a small, no-nonsense CRM you can stand up in a few minutes and make your own. Prospects, an activity timeline, follow-up reminders, and an optional shared mailbox, all in a single Node app with a plain PostgreSQL database and **no build step**.

The part that makes it different: it ships with a **Model Context Protocol (MCP) connector**. Point your AI assistant at it once and the assistant can read and write your CRM in plain language. Ask *"who owes me a follow-up?"*, say *"log that call and draft a reply"*, or *"add Helix Robotics as a prospect"*. No copy-paste, no CSV gymnastics.

> **Built by the [Castflow](https://castflow.co) team.** We originally built this CRM plus AI-connector stack for our own sales pipeline. It worked so well internally that we stripped it down to the reusable core and open-sourced it, so anyone can jump-start their own lightweight, personalized CRM with an AI connection, for free.

---

## Why you might want it

- **Own your data.** One Postgres database. No SaaS lock-in, no per-seat pricing.
- **AI-native.** The MCP connector is first-class, not a bolted-on integration. Your assistant uses the *same* API the dashboard uses.
- **Guided setup.** A built-in **MCP tab** shows your connector URL, checks the connection is live, and walks you through connecting Claude, ChatGPT, or Gemini.
- **Personalizable by design.** About 2,000 lines of readable, dependency-light code. Rename a field, add a status, change the theme. It is yours.
- **Lightweight.** Vanilla JS plus Tailwind (CDN) frontend, Express backend, no bundler, no framework churn.
- **Optional mailbox.** Turn on email (SMTP **or** Resend) and your assistant can read threads and send replies too. Leave it off and run CRM-only.

---

## See it

| Prospects and activity timeline | Shared mailbox | Built-in MCP setup |
|---|---|---|
| <img src="docs/images/crm.png" alt="CRM view" width="280"> | <img src="docs/images/mailbox.png" alt="Mailbox view" width="280"> | <img src="docs/images/mcp.png" alt="MCP setup and health check" width="280"> |

---

## What your AI can do with it

Once connected, your assistant has these tools. A real session looks like this:

> **You:** Any prospects I still owe a reply to?
>
> **Claude:** *(calls `crm_reminders`)* Two need attention:
> - **Northwind Studios**, follow-up due today, with a note "Budget approved for Q3."
> - **Helix Robotics**, they emailed about 200-seat pricing and you haven't replied.
>
> **You:** Log a call with Northwind, "confirmed Thursday demo, sending invite", and bump the follow-up to next Monday.
>
> **Claude:** *(calls `crm_add_activity`, then `crm_update_prospect`)* Done. Logged the call on Northwind Studios' timeline and moved the follow-up to Mon, Jul 20.
>
> **You:** Now reply to Helix with a friendly note that our team pricing starts at 200 seats, and offer a call.
>
> **Claude:** *(calls `mail_reply`)* Sent from `hello@relatio.example`, kept in the same thread. Want me to add Helix as an "Interested" prospect too?

Everything above is the assistant calling the connector's tools against your database. No manual entry.

<details>
<summary><b>Full tool list</b></summary>

**CRM:** `crm_list_prospects`, `crm_get_prospect`, `crm_create_prospect`, `crm_update_prospect`, `crm_delete_prospect`, `crm_add_activity`, `crm_delete_activity`, `crm_get_prospect_emails`, `crm_reminders`, `crm_list_statuses`, `crm_add_status`

**Mailbox** (when mail is enabled): `mail_list_mailboxes`, `mail_list_threads`, `mail_read_thread`, `mail_search`, `mail_send`, `mail_reply`, `mail_sync`

</details>

---

## Quick start (about 5 minutes)

You need **Node 20+** and a **PostgreSQL** database.

```bash
# 1. Get the code
git clone https://github.com/charbelkassab/relatio-crm.git
cd relatio-crm

# 2. Install
npm install

# 3. Configure
cp .env.example .env
#   then edit .env, at minimum set DATABASE_URL and OPERATOR_PASSWORD

# 4. Run (tables are created automatically on first start)
npm start
```

Open **http://localhost:3000**, sign in with your `OPERATOR_PASSWORD`, and you have a CRM. That is the whole setup.

Minimal `.env` to get going:

```env
DATABASE_URL=postgres://user:pass@localhost:5432/relatio
OPERATOR_PASSWORD=pick-a-password
SESSION_SECRET=any-long-random-string
```

> No Postgres yet? `docker run -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres` gives you one, then use `DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres`.

---

## Standalone, or drop it into your existing dashboard

Relatio runs two ways, no rewrite required:

- **Standalone** (the default): `npm start` gives you the full dashboard, REST API, and MCP connector on their own.
- **Embedded:** every piece is a plain Express router, so you can mount them straight into an app or admin dashboard you already have:

```js
const { migrate } = require('./relatio-crm/db/migrations');
await migrate(); // creates the crm_*, mailbox_*, and mcp_oauth_* tables

app.use('/api/crm', require('./relatio-crm/routes/crm'));         // CRM REST API
app.use('/api/mailbox', require('./relatio-crm/routes/mailbox')); // mailbox REST API
app.use('/', require('./relatio-crm/routes/mcp'));                // the MCP connector
```

Point it at your database with `DATABASE_URL`, gate the routes with your own auth, and the CRM, mailbox, and AI connector live inside your existing product. You can also ship just the connector: mount `routes/mcp` alone to put an MCP layer on top of a CRM you already run.

---

## Connect your AI assistant

The connector speaks standard **MCP over Streamable-HTTP with OAuth 2.1**, so any MCP-capable client works. The easiest path is the **MCP tab** in the dashboard: it shows your connector URL, runs a live health check, and lists every step.

First, set a shared secret and expose the app over HTTPS, then add the connector URL, which is **`https://your-domain.com/mcp`**.

```env
# add to .env, then restart
MCP_AUTH_SECRET=a-long-random-secret
PUBLIC_URL=https://your-domain.com
```

- **Claude** (web or desktop): Settings, Connectors, Add custom connector, paste `https://your-domain.com/mcp`. Claude walks the OAuth flow. When the access-key screen appears, paste your `MCP_AUTH_SECRET`.
- **ChatGPT, Gemini, or other MCP clients:** add a custom or remote MCP server with the same URL and complete the same one-time authorize step.

That is it. The CRM and mailbox tools show up in the assistant.

> **Local testing without a domain:** run [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector), point it at `http://localhost:3000/mcp`, and complete the authorize step to call tools directly.

---

## Configuration

| Variable | Purpose |
|---|---|
| `DATABASE_URL` | PostgreSQL connection string (**required**). |
| `PGSSL` | `require` if your database needs SSL (most managed DBs do). |
| `PORT`, `PUBLIC_URL` | Listen port, and public origin for the MCP flow. |
| `OPERATOR_PASSWORD` | Dashboard login. Blank **and** no `API_KEY` means open mode (localhost only). |
| `API_KEY` | Optional `X-Api-Key` for calling the REST API from scripts. |
| `SESSION_SECRET`, `COOKIE_SECURE` | Cookie signing. Set `COOKIE_SECURE=true` on HTTPS. |
| `MCP_AUTH_SECRET` | Enables the `/mcp` connector. The key typed once on the authorize screen. |
| `MAIL_PROVIDER` | `smtp`, `resend`, or blank (CRM-only). |
| `MAIL_ADDRESSES` | Comma-separated addresses this instance sends from and receives to. |
| `SMTP_*`, `IMAP_*` | SMTP send plus IMAP inbound (for `MAIL_PROVIDER=smtp`). |
| `RESEND_API_KEY` | Resend send plus inbound (for `MAIL_PROVIDER=resend`). |

See [`.env.example`](.env.example) for the full annotated list.

---

## Enabling mail (optional)

Mail is off until you pick a transport. Two options:

- **SMTP:** set `MAIL_PROVIDER=smtp` plus `SMTP_HOST/PORT/USER/PASS` (sending) and `IMAP_*` (inbound polling). Works with Gmail app-passwords, Fastmail, your own server, and similar.
- **Resend:** set `MAIL_PROVIDER=resend` and `RESEND_API_KEY`. Inbound uses a Resend receiving domain.

Either way, the dashboard mailbox, the REST API, and the `mail_*` MCP tools all read and write the same store, so nothing drifts.

---

## Architecture (the whole thing on one page)

```
server.js            Express bootstrap: session, migrations, routes, mail-sync timer
db/                  pool.js (pg) plus migrations.js (idempotent schema)
middleware/auth.js   single-operator gate (session cookie or X-Api-Key)
routes/
  crm.js             CRM REST API
  mailbox.js         lean shared-inbox REST API
  mcpStatus.js       connector status for the MCP dashboard tab
  mcp/               OAuth 2.1 server plus Streamable-HTTP MCP endpoint plus tools/
services/mail/       transport abstraction: smtp.js or resend.js into a shared store.js
public/              dashboard: index.html plus app.js plus dialogs.js (no build step)
```

**Design principle:** the dashboard, the REST API, and the MCP tools all funnel through the same queries and the same mail store, so a human clicking the UI and an AI calling a tool can never see different data.

---

## Security notes

- The `/mcp` endpoint is gated by `MCP_AUTH_SECRET` (OAuth 2.1 plus PKCE, tokens stored hashed). Use a long random secret and serve over HTTPS.
- The dashboard is single-operator. For anything public-facing, always set `OPERATOR_PASSWORD` (or `API_KEY`) and `COOKIE_SECURE=true`.
- `mail_send` and `mail_reply` deliver **real email**. Your assistant will confirm before sending.

---

## Credits and license

Built and open-sourced by the **[Castflow](https://castflow.co)** team, extracted from the internal CRM plus AI-connector tooling we use to run our own pipeline, and shared so you can start your own in an afternoon.

MIT licensed. Use it, fork it, make it yours. If it helps you, a star on the repo is appreciated.