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

Related MCP server: Airtable MCP Server

二、安裝

懶人路線：把這個 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 官網。

本 server 依賴 mcp 1.x（mcp.server.fastmcp）。mcp 2.0 已移除該模組，新裝會在 import 時崩潰。已驗證的 interpreter 是 Python 3.12。若已裝到壞掉的版本，重裝：

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

三、設定 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-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 的詳細參數、where 過濾語法、子表格寫入格式寫在 AGENTS.md。

七、安全設計

依然要遵守的最佳實務：

• API key 給最小權限（read-only 就好的場景不要發 write key）

• 不要把 ~/.config/ragic-mcp/config.json 拷貝到雲端硬碟或截圖外傳

• 懷疑外流時：Ragic 後台 revoke → 重新跑 ragic-mcp setup

八、Ragic 限速

• 同時待處理佇列 50 個

• 持續超過 5 req/sec 會被人工審查

九、回報問題

GitHub Issues

十一、CLI 直接操作資料

除了 MCP server 模式，ragic-mcp 也提供 11 個子指令讓你在 terminal 直接讀寫 Ragic，無需 MCP client。

安裝

uv tool install --editable /path/to/ragic-mcp   # 本機開發版
# 或從 GitHub 安裝正式版：
uv tool install git+https://github.com/EthanH9977/ragic-mcp.git

設定 credentials 同 MCP 模式（ragic-mcp setup），CLI 讀同一份 ~/.config/ragic-mcp/config.json。

全域選項：--config <路徑> 可覆寫設定檔路徑。

子指令速查

結果輸出為 JSON（stdout）；錯誤輸出到 stderr 且 exit code 非 0；delete-record/approve 無 --yes 時 exit 2 且不呼叫 API。

範例：

# 列出所有表
ragic-mcp list-sheets

# 列出前 3 筆（FNAME 欄位名稱）
ragic-mcp list-records sales 1 --limit 3

# 讀單筆
ragic-mcp get-record sales 1 12345

# 全文搜尋
ragic-mcp search sales 1 "Acme Corp"

# 查 filter 語法
ragic-mcp filter-help

# 刪除（需 --yes）
ragic-mcp delete-record sales 1 12345 --yes

與 MCP 併存

CLI 與 MCP server 完全複用同一份 client 與 config，無需額外設定。若你的 AI assistant 已透過 MCP 連接 Ragic，CLI 仍可在 terminal 獨立使用，兩者不衝突。

十二、授權

MIT