使用手冊

開源 CRM / AI Agent · 自架

Agent 原生的開源 CRM。資料留在你手上。

Relaticle 是內建 30 個 MCP 工具與 REST API 的開源自架 CRM,以 Laravel 12 + Filament 5 打造。本手冊涵蓋自架安裝、MCP 工具總覽、AI agent 連接設定與實戰範例。

Relaticle 是一套自架的開源 CRM,內建 30 個 MCP 工具與 REST API,讓 Claude、GPT 或開源模型能直接讀寫公司、聯絡人、商機、任務與筆記。以 Laravel 12 與 Filament 5 打造,支援 22 種自訂欄位、多團隊隔離與逐欄位加密。本手冊涵蓋自架安裝、MCP 工具總覽、agent 連接設定與實戰範例。

relaticle/relaticle
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
8 分
更新日期
開啟原始報告
GitHub Stars
1.3k
MCP 工具
30
自訂欄位型別
22
開源授權 3.0
AGPL
本頁章節

01這到底是什麼

一套自架的開源 CRM, 從第一天就為 agent 設計。

Relaticle 是一套開源的客戶關係管理(CRM)系統,主打自架部署與 AI agent 整合。傳統 CRM 把 API 當成事後補上的整合層;Relaticle 把 agent 存取列為核心:內建 MCP(Model Context Protocol)伺服器,提供 30 個工具,讓 Claude、GPT 或開源模型能直接操作 CRM 資料,而資料因為自架,完全留在你自己的伺服器上。

系統以 Laravel 12 與 Filament 5 建構,前端使用 Livewire 4,執行於 PHP 8.4 與 PostgreSQL 17。核心實體有五類:公司(Companies)、聯絡人(People)、商機(Opportunities)、任務(Tasks)、筆記(Notes)。每一類都支援 22 種自訂欄位型別,包含實體關聯與條件式顯示,因此資料模型可依業務調整,而非套用固定欄位。

資料安全是內建設計的一部分。Relaticle 採多團隊隔離,以五層授權控管存取;敏感欄位可逐欄位加密;專案附帶 1,100+ 自動化測試。MCP 工具透過團隊範圍的存取權杖驗證,agent 取得的權限受權杖能力(token abilities)約束,而非全域開放。

  1. Companies

  2. People

  3. Opportunities

  4. Tasks

  5. Notes

Open-source CRM with native AI agent support. 30 MCP tools, REST API, self-hosted.

— Relaticle 官方專案說明,GitHub

02自架安裝

一行 composer 指令, 把 CRM 跑在你自己的機器上。

環境需求:PHP 8.4+、PostgreSQL 17+、Composer 2、Node.js 20+;佇列若要啟用可加裝 Redis(開發環境可選)。clone 專案後,composer app-install 會完成依賴安裝、環境設定與資料庫初始化。

bash
# 1. 取得原始碼
git clone https://github.com/Relaticle/relaticle.git

# 2. 進入目錄並執行一鍵安裝
cd relaticle && composer app-install

開發指令

安裝完成後,以下指令涵蓋日常開發:composer dev 啟動本機開發環境,composer test 跑測試套件,composer lint 檢查程式碼風格。

bash
composer dev      # 啟動本機開發伺服器
composer test     # 執行 1,100+ 自動化測試
composer lint     # 程式碼風格檢查

0330 個 MCP 工具

Agent 能操作的每一個動作。

Relaticle 的 MCP 伺服器提供 30 個工具,涵蓋六個分類。除帳號查詢外,五類核心實體(公司、聯絡人、商機、任務、筆記)都提供完整 CRUD;任務與筆記另有附掛/卸除工具,可在不破壞既有關聯的前提下,把它們連結到其他實體。所有 list 工具支援搜尋與分頁(per_page、page),create/update 工具接受 custom_fields。

1 tool

Account

帳號查詢

whoami — 取得目前驗證的使用者、所屬團隊與權杖能力(token abilities)。

5 tools

Companies

公司管理

list、get、create、update、delete。完整 CRUD,list 支援搜尋與分頁。

5 tools

People

聯絡人管理

list、get、create、update、delete。聯絡人的完整 CRUD 操作。

5 tools

Opportunities

商機管理

list、get、create、update、delete。交易/商機的完整 CRUD。

7 tools

Tasks

任務管理

CRUD 五項,外加 attach_task_to_entities 與 detach_task_from_entities 兩項關聯工具。

7 tools

Notes

筆記管理

CRUD 五項,外加附掛/卸除工具,可把筆記連結到其他實體而不破壞既有關聯。

連接你的 AI agent

在 Relaticle 的 Settings > Access Tokens 建立存取權杖,權杖會綁定你建立時選擇的團隊。MCP 端點為 https://mcp.relaticle.com,採 streamable-http 傳輸。以 Claude Code 為例:

bash
claude mcp add relaticle \
  --transport streamable-http \
  https://mcp.relaticle.com \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop、Cursor 或 VS Code 則以 JSON 設定:

json
{
  "mcpServers": {
    "relaticle": {
      "type": "streamable-http",
      "url": "https://mcp.relaticle.com",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

04關鍵特性 · 依官方文件

讓 agent 用得安全又到位的設計。

以下整理自官方文件,是 Relaticle 在 agent 場景下值得先掌握的設計。重點不在工具數量,而在資料模型彈性、權限邊界與資料完整性如何協同運作。

權杖綁定團隊,而非全域

建立存取權杖時要選定團隊,該權杖之後只能存取那個團隊的資料,且建立後不可重複取得。agent 拿到的權限受權杖能力約束,操作預設落在權杖所屬團隊。

來源 · relaticle.com/docs/mcp

create/update 接受 custom_fields

22 種自訂欄位型別不只在 UI 可用,MCP 的 create 與 update 工具也接受 custom_fields 參數。agent 寫入時能直接填自訂欄位,不必受限於內建欄位。

來源 · relaticle.com/docs/mcp

附掛工具不會破壞既有關聯

任務與筆記的 attach / detach 工具設計為加減關聯,而非覆寫。agent 可以把一個任務連到多個實體,或卸除單一連結,而不影響其他既有關聯。

來源 · relaticle.com/docs/mcp

list 一律支援搜尋與分頁

所有 list 工具支援搜尋與 per_page / page 分頁,並受 REST API 的速率限制約束。agent 在大型資料集上查詢時,以分頁逐批取得,而非一次拉滿。

來源 · relaticle.com/docs/mcp

刪除為軟刪除,保全資料完整性

delete 工具採軟刪除(soft-delete),記錄不會立即實體消失。即使 agent 誤刪,資料仍可追溯,降低自動化操作的不可逆風險。

來源 · relaticle.com/docs/mcp

敏感欄位可逐欄位加密

Relaticle 支援逐欄位(per-field)加密,搭配多團隊隔離與五層授權。把 CRM 自架在自己的基礎設施,再對敏感欄位加密,是處理客戶資料時的基本防線。

來源 · Relaticle GitHub · 功能清單

05實戰範例

用自然語言, 讓 agent 讀寫你的 CRM。

以下示範一段情境:Relaticle MCP 已連上 Claude Code。你用自然語言請 agent 建立一家新公司、加上聯絡人、開一筆商機,並掛上後續任務。agent 透過 MCP 工具完成每一步,先以 schema 探索得知可寫欄位,再呼叫對應的 create 與 attach 工具。

claude code · relaticle mcp · streamable-http


$ You ›
  幫我把今天會議的客戶建進 CRM:公司 Acme Robotics,
  窗口 Lin Wei,開一筆導入專案的商機,並排一個下週跟進的任務。


# [mcp: relaticle · reading schema resources]
# [whoami → team: Sales TW · abilities: read, write]


claude: Claude ›
  已連上 Relaticle(團隊 Sales TW)。我會分四步建立,
  先讀各實體 schema 確認可寫欄位,再依序建立。


# [1/4] companies.create
    name: "Acme Robotics"
    custom_fields: { industry: "Robotics", region: "APAC" }
  ok: ✓ company #1042 created


# [2/4] people.create
    name: "Lin Wei" · company_id: 1042
    custom_fields: { title: "VP Engineering" }
  ok: ✓ person #2087 created


# [3/4] opportunities.create
    name: "Acme — 導入專案" · company_id: 1042
    custom_fields: { stage: "Discovery", value: 80000 }
  ok: ✓ opportunity #318 created


# [4/4] tasks.create + attach_task_to_entities
    title: "跟進 Acme 導入需求" · due: 下週一
    attach → company #1042, opportunity #318
  ok: ✓ task #905 created · linked to 2 entities


claude: Claude ›
  完成。已建立 1 家公司、1 位聯絡人、1 筆商機,
  並把跟進任務同時掛到公司與商機上。


$ You ›
  列出 Sales TW 團隊目前 Discovery 階段的商機。


# [opportunities.list · search: "Discovery" · per_page: 20]
  hl: #318 Acme — 導入專案 · 80,000 · Discovery
  # … 範圍限於權杖所屬團隊 Sales TW

agent 先讀 schema 得知可寫欄位,再呼叫 create 與 attach 工具。 每一步都受權杖的團隊範圍與能力約束。

— Relaticle MCP 的標準操作流程

這段操作為什麼值得拆解

agent 沒有硬編欄位,而是先讀 schema 資源確認每個實體可寫什麼,再填入 custom_fields。這讓同一段自然語言指令,能適配不同團隊各自客製的資料模型。

其次,所有操作都落在權杖所屬團隊 Sales TW。即使 prompt 沒指定團隊,寫入與查詢的範圍也由權杖決定,而非 agent 自由選擇。這是把 CRM 開放給自動化時的權限邊界。

06先看清楚這些

上線前, 先確認這些前提。

07進階路徑

從跑起來,到接進你的流程。

裝好之後,下一步是把 Relaticle 接進實際工作流程。資料層、agent 層、自訂層各有可延伸之處,以下是建議的推進順序。

進階推進地圖

**1. 設計你的自訂欄位模型。**22 種欄位型別含實體關聯與條件式顯示。先把業務真正需要的欄位建好,因為 MCP 的 create / update 會直接用到這些 custom_fields。

**2. 用 REST API 做批次與整合。**除 MCP 外,Relaticle 提供 REST API。表單填寫、資料匯入、與其他系統同步等非對話式整合,走 REST API 比逐次 agent 呼叫更穩定。

**3. 規劃多團隊與授權。**多團隊隔離搭配五層授權,適合一個實例服務多個團隊。先設計團隊邊界與權杖分配,再開放 agent 存取。

**4. 為敏感資料開啟逐欄位加密。**對含個資或商業機密的欄位啟用 per-field 加密,結合自架的資料主權,降低資料外洩面。

**5. 串接多個 MCP 客戶端。**同一個端點可供 Claude Code、Claude Desktop、Cursor、VS Code 使用。為不同用途建立不同團隊範圍的權杖,以隔離權限。

最該讀的三份官方文件

① relaticle.com/docs——產品與功能總覽。 ② relaticle.com/docs/mcp——MCP 工具清單、連接設定與權限說明。 ③ relaticle.com/docs/self-hosting——自架部署的完整步驟。

22 customizable field types · multi-team isolation with 5-layer authorization · per-field encryption 1,100+ automated tests.

— Relaticle 功能清單,GitHub