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: Database 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 官網。

三、設定 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

十、授權

MIT