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

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

_{Log a call, draft a reply, then check the AI connector. Same data your assistant reads and writes over MCP.}

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

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

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:

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.

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