ragic-mcp

讓 AI（Claude Desktop、Claude Code、其他 MCP client）直接操作 Ragic 的 MCP server。11 個 tool 涵蓋表單探索、讀取、寫入、簽核、上鎖。

權限完全由 Ragic 那邊的 API key 控制——key 是 read-only，寫入類 tool 就會收到 Ragic 的權限錯誤；key 有寫入權限就全用得到。

AI 怎麼用這個 server 看 AGENTS.md。這份檔案只講「給人類的安裝與設定」。

---

一、需要的東西

• Ragic 帳號與有效 API key（Ragic 後台 → 個人設定 → 帳號設定 → API key）
• Python 3.10+
• uv（推薦）：brew install uv 或 pip install uv

---

二、安裝

懶人路線：把這個 repo 網址 https://github.com/EthanH9977/ragic-mcp 貼給你的 AI，說「幫我裝這個 MCP」。AI 會照 AGENTS.md §0 的 6 步流程自動跑完安裝＋設定＋註冊到 MCP client。下面是手動流程：

uv tool install git+https://github.com/EthanH9977/ragic-mcp.git

裝完 ragic-mcp 命令會自動在 PATH 裡，任何 terminal 直接跑。確認：

which ragic-mcp
# 應該回：/Users/<你>/.local/bin/ragic-mcp

沒裝 uv？brew install uv（macOS）或看 uv 官網。

---

三、設定 credentials（一次就好）

在 terminal 跑：

ragic-mcp setup

這會：

1. 在 ~/.config/ragic-mcp/config.json 建立一份模板（檔案權限自動 0600，只有你本人能讀）
2. 用你系統預設的文字編輯器（macOS = TextEdit、Windows = Notepad、Linux = $EDITOR）打開
3. 你直接在編輯器裡填三個值，存檔關閉

模板長這樣，把右邊三個值換成你的：

{
  "RAGIC_SERVER": "ap5.ragic.com",
  "RAGIC_ACCOUNT": "your_account_here",
  "RAGIC_API_KEY": "paste_your_api_key_here"
}

欄位	取自你 Ragic 表單網址 https://{server}/{account}/{path}/{sheet}
RAGIC_SERVER	ap5.ragic.com、www.ragic.com、na3.ragic.com、eu2.ragic.com 其中一個
RAGIC_ACCOUNT	網域後第一段
RAGIC_API_KEY	Ragic 後台 → 個人設定 → 帳號設定 → API key

其他相關指令

ragic-mcp show     # 顯示目前設定（API key 自動 mask 成首尾 4 碼）
ragic-mcp clear    # 刪除本機 config
ragic-mcp serve    # 啟動 MCP server（預設行為，給 client 呼叫）

如果你不想存到檔案，也可以用環境變數覆蓋（env var 優先序高於 config 檔）：

RAGIC_SERVER=... RAGIC_ACCOUNT=... RAGIC_API_KEY=... ragic-mcp

---

四、接到 MCP client

Claude Desktop

打開 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），加入：

{
  "mcpServers": {
    "ragic": {
      "command": "ragic-mcp"
    }
  }
}

注意：command 要寫成 ragic-mcp 可被 PATH 找到。如果你是裝在 venv，要寫絕對路徑，例如： /path/to/your/venv/bin/ragic-mcp

存檔後重啟 Claude Desktop。

Claude Code

claude mcp add --scope user ragic ragic-mcp

（如果 ragic-mcp 不在 PATH，改成絕對路徑。）

其他 MCP client

任何支援 stdio transport 的 client 都行。指令一律是：

ragic-mcp

---

五、驗證

在 MCP client 對話視窗問：

呼叫 ragic_filter_help 看 cheatsheet

收到一份 Ragic API filter cheatsheet 就表示通了。

接著測讀取——直接讓 AI 自己探索你的表：

用 ragic_list_sheets 列出我所有可以讀的表

AI 拿到表清單後就能直接幫你查特定表，不用再貼網址。

---

六、提供的 tool（11 個）

Tool	動作	API key 需要的權限
ragic_list_sheets	列出帳號下所有可讀的表（含中文名、path、sheet_index）	read
ragic_list_records	列表＋過濾＋排序＋分頁	read
ragic_get_record	讀單筆	read
ragic_search	全文檢索	read
ragic_create_record	新增（含子表）	write
ragic_update_record	局部更新欄位	write
ragic_delete_record	刪除單筆	write
ragic_approve	簽核（approve／reject）	approval
ragic_lock	上鎖	write
ragic_unlock	解鎖	write
ragic_filter_help	取 filter／參數速查表	—

每個 tool 的詳細參數、where 過濾語法、子表格寫入格式寫在 AGENTS.md。

---

七、安全設計

防線	怎麼擋
API key 不入 git	.env、config.json 都在 .gitignore，setup 寫的也不在 repo 內
API key 不外流	設定檔權限 0600；ragic-mcp show 自動 mask 為首尾 4 碼
API key 不入 shell history	setup 用編輯器流程，key 由使用者貼進 config 檔，不經過 terminal 輸入
主機白名單	client 拒絕非 *.ragic.com 主機，防止打錯網址把 Authorization 送到攻擊者
不跟 redirect	httpx.AsyncClient(follow_redirects=False)，防 3xx 把 header 帶到第三方
寫入錯誤偵測	Ragic 寫入失敗會回 HTTP 200 + {"status":"ERROR"}，client 已轉成例外

依然要遵守的最佳實務：

• API key 給最小權限（read-only 就好的場景不要發 write key）
• 不要把 ~/.config/ragic-mcp/config.json 拷貝到雲端硬碟或截圖外傳
• 懷疑外流時：Ragic 後台 revoke → 重新跑 ragic-mcp setup

---

八、Ragic 限速

• 同時待處理佇列 50 個
• 持續超過 5 req/sec 會被人工審查

---

九、回報問題

GitHub Issues

---

十、授權

MIT