實戰手冊 · Field Manual v3.3.7 · 2026

github.com/Relaticle/relaticle · 1.3k ★

開源 CRM / AI Agent · 自架

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

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

1.3k

GitHub Stars

MCP 工具

自訂欄位型別

AGPL

開源授權 3.0

這到底是什麼

一套自架的開源 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)約束,而非全域開放。

Relaticle · 五類核心實體

Companies· People· Opportunities· Tasks· Notes

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

— Relaticle 官方專案說明,GitHub

自架安裝

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

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

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

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

開發指令

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

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

不必自架也能試。官方提供託管版本與完整文件:產品網站 relaticle.com、文件 relaticle.com/docs、自架指南 relaticle.com/docs/self-hosting。自架的核心理由是資料主權——CRM 資料與 agent 存取都留在你自己的基礎設施內。

30 個 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 為例:

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

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

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

Schema 探索。MCP 伺服器另有五個 schema 資源,公開各實體的欄位(含自訂欄位)。agent 會自動讀取,因此能在不靠人工說明的情況下,得知每個實體有哪些欄位可寫。

關鍵特性 · 依官方文件

讓 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 · 功能清單

實戰範例

用自然語言,
讓 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 › 已連上 Relaticle(團隊 Sales TW)。我會分四步建立, 先讀各實體 schema 確認可寫欄位,再依序建立。

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

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

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

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

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

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

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

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

— Relaticle MCP 的標準操作流程

這段操作為什麼值得拆解

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

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

先看清楚這些

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

自架需要維運能力。Relaticle 要 PHP 8.4、PostgreSQL 17、Composer 與 Node.js 20。自架代表升級、備份、安全更新都由你負責。若不想維運基礎設施,評估官方託管版本。
PostgreSQL 17 是硬需求。文件指定 PostgreSQL 17 以上,而非泛用任意資料庫。部署前先確認你的環境能提供對應版本,避免遷移後相容性問題。
AGPL-3.0 有義務。授權為 AGPL-3.0。若你以網路服務形式對外提供改作版本,須依授權公開對應原始碼。商用整合前先確認是否符合你的合規需求。
給 agent 寫入權前先想清楚範圍。MCP 工具含 create / update / delete。權杖雖綁團隊,但在該團隊內 agent 能寫入與刪除。對自動化流程,建議先用最小權限的權杖測試。
軟刪除不等於無痕。delete 採軟刪除可降低誤刪風險,但被軟刪的資料仍存在於資料庫。若有真正的資料清除(硬刪除)或保留政策需求,需另行規劃。
權杖即憑證,妥善保管。MCP 以 Authorization: Bearer 標頭帶權杖。權杖外洩等同團隊資料外洩。存放於環境變數或秘密管理工具,不要寫進版本控管。
速率限制沿用 REST API。MCP 的 list 等操作受 REST API 速率限制約束。大量批次操作時,以分頁逐批處理,避免觸發限流而中斷流程。
star 數不代表成熟度。本手冊數據為撰寫時抓取(1.3k stars、v3.3.7)。版本更新可能調整工具集或欄位行為,正式整合前以官方文件 relaticle.com/docs 為準。

進階路徑

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

裝好之後,下一步是把 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

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

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

開發指令

Agent 能操作的每一個動作。

連接你的 AI agent

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

權杖綁定團隊,而非全域

create/update 接受 custom_fields

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

list 一律支援搜尋與分頁

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

敏感欄位可逐欄位加密

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

這段操作為什麼值得拆解

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

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

進階推進地圖

最該讀的三份官方文件

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

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

Agent 能操作的
每一個動作。

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

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

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