内容
<div align="center">
# Relatio，一款轻量级、可个性化的CRM
### 一个小巧、自主托管的CRM，内置 **MCP连接器**，让您的AI可以为您运行。
**与Claude、ChatGPT、Gemini或任何兼容MCP的助手配合使用。**
<!-- 替换为您自己的存储库链接，一旦发布 -->
<br>
<img src="docs/images/demo.gif" alt="Relatio CRM 在运行：记录活动、草拟电子邮件回复以及测试 MCP 连接器" width="850">
<sub>记录通话、草拟回复，然后检查 AI 连接器。您的助手通过 MCP 读取和写入相同的数据。</sub>
</div>
---
## 这是什么？
**Relatio** 是一个小而精致的CRM，您可以在几分钟内建立并使其属于您。潜在客户、活动时间线、后续提醒和可选的共享邮箱，都在一个Node应用程序中，使用普通的PostgreSQL数据库，**无需构建步骤**。
使其与众不同的部分：它配备了 **模型上下文协议（MCP）连接器**。将您的AI助手指向它一次，助手就可以用纯语言读取和写入您的CRM。询问 *"谁需要我跟进？"*，说 *"记录该通话并草拟回复"*，或 *"将Helix Robotics添加为潜在客户"*。无需复制粘贴，无需CSV操作。
> **由 [Castflow](https://castflow.co) 团队构建。** 我们最初为自己的销售渠道构建了这个CRM和AI连接器堆栈。在内部它运行得非常好，我们将其精简到可重用的核心并开源，以便任何人都可以免费启动自己的轻量级、可个性化的CRM和AI连接。
---
## 为什么您可能需要它
- **拥有您的数据。** 一个Postgres数据库。无SaaS锁定，无每席位定价。
- **AI原生。** MCP连接器是一流的，而不是一个附加集成。您的助手使用与仪表板相同的 **API**。
- **引导式设置。** 内置的 **MCP选项卡** 显示您的连接器URL，检查连接是否正常，并引导您连接Claude、ChatGPT或Gemini。
- **可个性化设计。** 约2000行可读、依赖关系轻的代码。重命名字段、添加状态、更改主题。它是您的。
- **轻量级。** 普通JavaScript加上Tailwind（CDN）前端，Express后端，无打包器，无框架变更。
- **可选邮箱。** 打开电子邮件（SMTP **或** Resend），您的助手也可以读取线程并发送回复。关闭它，运行仅CRM。
---
## 看看
| 潜在客户和活动时间线 | 共享邮箱 | 内置MCP设置 |
|---|---|---|
| <img src="docs/images/crm.png" alt="CRM视图" width="280"> | <img src="docs/images/mailbox.png" alt="邮箱视图" width="280"> | <img src="docs/images/mcp.png" alt="MCP设置和健康检查" width="280"> |
---
## 您的AI可以与它做什么
连接后，您的助手拥有这些工具。实际会话如下所示：
> **您：** 还有哪些潜在客户我需要回复？
>
> **Claude：** *(调用 `crm_reminders`)* 两个需要关注：
> - **Northwind Studios**，今天到期，跟进备注“Q3预算已批准。”
> - **Helix Robotics**，他们发送了关于200席位定价的电子邮件，但您尚未回复。
>
> **您：** 记录与Northwind的通话，“确认周四演示，发送邀请”，并将跟进时间推迟到下周一。
>
> **Claude：** *(调用 `crm_add_activity`，然后 `crm_update_prospect`)* 已完成。在Northwind Studios的时间线中记录了通话，并将跟进时间推迟到7月20日，星期一。
>
> **您：** 现在给Helix发送友好备注，我们的团队定价从200席位开始，并提供通话。
>
> **Claude：** *(调用 `mail_reply`)* 从 `hello@relatio.example` 发送，保持在同一线程中。是否需要将Helix添加为“感兴趣”的潜在客户？
以上所有操作都是助手调用连接器的工具来操作您的数据库。无需手动输入。
<details>
<summary><b>完整工具列表</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`
**邮箱** （启用邮件时）：`mail_list_mailboxes`、`mail_list_threads`、`mail_read_thread`、`mail_search`、`mail_send`、`mail_reply`、`mail_sync`
</details>
---
## 快速开始（约5分钟）
您需要 **Node 20+** 和一个 **PostgreSQL** 数据库。
```bash
# 1. 获取代码
git clone https://github.com/charbelkassab/relatio-crm.git
cd relatio-crm
# 2. 安装
npm install
# 3. 配置
cp .env.example .env
# 然后编辑 .env，至少设置 DATABASE_URL 和 OPERATOR_PASSWORD
# 4. 运行（首次启动时自动创建表）
npm start
```
打开 **http://localhost:3000**，使用您的 `OPERATOR_PASSWORD` 登录，就拥有了一个CRM。 这就是整个设置。
最小 `.env` 配置：
```env
DATABASE_URL=postgres://user:pass@localhost:5432/relatio
OPERATOR_PASSWORD=选择一个密码
SESSION_SECRET=任意长的随机字符串
```
> 还没有Postgres？ `docker run -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres` 给您一个，然后使用 `DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres`。
---
## 独立运行，或集成到现有仪表板
Relatio有两种运行方式，无需重写：
- **独立运行** （默认）：`npm start` 为您提供完整的仪表板、REST API和MCP连接器。
- **嵌入式：** 每个部分都是一个普通的Express路由器，因此您可以将它们直接挂载到您已经拥有的应用程序或管理仪表板中：
```js
const { migrate } = require('./relatio-crm/db/migrations');
await migrate(); // 创建 crm_*、mailbox_* 和 mcp_oauth_* 表
app.use('/api/crm', require('./relatio-crm/routes/crm')); // CRM REST API
app.use('/api/mailbox', require('./relatio-crm/routes/mailbox')); // 邮箱 REST API
app.use('/', require('./relatio-crm/routes/mcp')); // MCP 连接器
```
使用 `DATABASE_URL` 指向您的数据库，使用您的身份验证保护路由，CRM、邮箱和AI连接器将生活在您的现有产品中。您还可以只提供连接器：挂载 `routes/mcp` 以在您已经运行的CRM上添加MCP层。
---
## 连接您的AI助手
连接器通过 **Streamable-HTTP上的标准MCP与OAuth 2.1**，因此任何MCP客户端都可以使用。最简单的路径是仪表板中的 **MCP选项卡**：它显示您的连接器URL，运行健康检查，并列出每个步骤。
首先，设置共享密钥并将应用程序暴露在HTTPS下，然后添加连接器URL，即 **`https://your-domain.com/mcp`**。
```env
# 添加到 .env，然后重启
MCP_AUTH_SECRET=一个长随机密钥
PUBLIC_URL=https://your-domain.com
```
- **Claude** （网页或桌面版）：设置，连接器，添加自定义连接器，粘贴 `https://your-domain.com/mcp`。Claude会引导OAuth流程。当出现访问密钥屏幕时，粘贴您的 `MCP_AUTH_SECRET`。
- **ChatGPT、Gemini或其他MCP客户端：** 使用相同的URL添加自定义或远程MCP服务器，并完成相同的授权步骤。
就是这样。CRM和邮箱工具会在助手中显示。
> **在没有域的情况下进行本地测试：** 运行 [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector)，指向 `http://localhost:3000/mcp`，并完成授权步骤以直接调用工具。
---
## 配置
| 变量 | 用途 |
|---|---|
| `DATABASE_URL` | PostgreSQL连接字符串（**必填**）。 |
| `PGSSL` | 如果您的数据库需要SSL（大多数托管数据库都需要）。 |
| `PORT`、`PUBLIC_URL` | 监听端口和MCP流程的公共源。 |
| `OPERATOR_PASSWORD` | 仪表板登录。空白 **且** 没有 `API_KEY` 意味着开放模式（仅限localhost）。 |
| `API_KEY` | 用于从脚本调用REST API的 `X-Api-Key`。 |
| `SESSION_SECRET`、`COOKIE_SECURE` | Cookie签名。在HTTPS上设置 `COOKIE_SECURE=true`。 |
| `MCP_AUTH_SECRET` | 启用 `/mcp` 连接器。授权屏幕上输入的密钥。 |
| `MAIL_PROVIDER` | `smtp`、`resend` 或空白（仅CRM）。 |
| `MAIL_ADDRESSES` | 以逗号分隔的地址，此实例发送和接收邮件。 |
| `SMTP_*`、`IMAP_*` | SMTP发送和IMAP接收（适用于 `MAIL_PROVIDER=smtp`）。 |
| `RESEND_API_KEY` | Resend发送和接收（适用于 `MAIL_PROVIDER=resend`）。 |
参见 [`.env.example`](.env.example) 了解完整的注释列表。
---
## 启用邮件（可选）
邮件关闭，直到您选择一种传输方式。两个选项：
- **SMTP：** 设置 `MAIL_PROVIDER=smtp` 加 `SMTP_HOST/PORT/USER/PASS`（发送）和 `IMAP_*`（接收轮询）。适用于Gmail应用密码、Fastmail、您自己的服务器等。
- **Resend：** 设置 `MAIL_PROVIDER=resend` 和 `RESEND_API_KEY`。接收使用Resend接收域。
无论哪种方式，仪表板邮箱、REST API和 `mail_*` MCP工具都会读写相同的存储，因此不会有数据漂移。
---
## 架构（整个架构在一页上）
```
server.js Express引导：session、migrations、routes、mail-sync timer
db/ pool.js（pg）加 migrations.js（幂等模式）
middleware/auth.js 单操作员门控（session cookie或X-Api-Key）
routes/
crm.js CRM REST API
mailbox.js 精简共享邮箱REST API
mcpStatus.js MCP仪表板选项卡的连接器状态
mcp/ OAuth 2.1服务器加Streamable-HTTP MCP端点加tools/
services/mail/ 传输抽象：smtp.js或resend.js进入shared store.js
public/ 仪表板：index.html加app.js加dialogs.js（无构建步骤）
```
**设计原则：** 仪表板、REST API和MCP工具都通过相同的查询和相同的邮件存储，因此人类点击UI和AI调用工具永远不会看到不同的数据。
---
## 安全说明
- `/mcp` 端点由 `MCP_AUTH_SECRET` （OAuth 2.1 加 PKCE，令牌存储为哈希）保护。使用长随机密钥并在 HTTPS 上提供服务。
- 仪表板是单操作员的。对于任何公开的界面，请始终设置 `OPERATOR_PASSWORD` （或 `API_KEY`）和 `COOKIE_SECURE=true`。
- `mail_send` 和 `mail_reply` 发送 **真实电子邮件**。您的助手在发送前会确认。
---
## 致谢与许可
由 **[Castflow](https://castflow.co)** 团队构建和开源，从我们用于运行自身渠道的内部CRM和AI连接器工具中提取出来，并共享给您，以便您可以在一个下午内启动自己的工具。
MIT许可。 使用它，修改它，使它成为您自己的。 如果它对您有帮助，仓库上的一颗星是赞赏。
