REST API v1 · 開發者
MCP 伺服器:用 AI 助理管理你的 Discord 伺服器
BotGG 提供遠端的 Model Context Protocol 伺服器。把 AI 助理連上去之後,它就能使用與 REST API 相同的端點(權限範圍、限制與檢查也都相同),操作你授權的那一個伺服器。
開發者文件
本頁目錄
連接用戶端
伺服器網址是 https://console.botgg.app/mcp(透過 Streamable HTTP 使用 MCP)。用戶端有兩種登入方式:
- 使用 Discord 登入(OAuth),建議使用。 用戶端只需要這個網址。它會在瀏覽器中開啟 BotGG,你用 Discord 登入、選擇一個伺服器與權限,然後同意即可。不需要複製任何東西,也能隨時中斷應用程式的連線。
- API 金鑰。 適用於不支援 OAuth 的用戶端:在控制台建立金鑰(請見驗證),並以
Authorization: Bearer botgg_…傳送。
Claude(claude.ai 與 Claude Desktop)
- 開啟 Settings → Connectors,然後選擇 Add custom connector。
- 將它命名為
BotGG,並貼上https://console.botgg.app/mcp作為網址,然後按 Add。 - 按下 Connect:BotGG 會開啟,你用 Discord 登入並同意(請見同意畫面)。
ChatGPT
- 開啟 Settings → Apps & Connectors。自訂連接器需要在你的方案中啟用 Developer mode(位於 Advanced settings)。
- 選擇 Create,將它命名為
BotGG,貼上https://console.botgg.app/mcp作為 MCP 伺服器網址,並將驗證方式選為 OAuth。 - 建立連接器後,在 ChatGPT 開啟 BotGG 時登入。
Cursor
把伺服器加入 ~/.cursor/mcp.json(或專案的 .cursor/mcp.json)。Cursor 會在旁邊顯示 Needs login,點一下即可在瀏覽器中用 Discord 登入。
{
"mcpServers": {
"botgg": { "url": "https://console.botgg.app/mcp" }
}
}Claude Code
claude mcp add --transport http botgg https://console.botgg.app/mcp
# then run /mcp inside Claude Code and choose "Authenticate"任何使用 API 金鑰的用戶端
{
"mcpServers": {
"botgg": {
"type": "http",
"url": "https://console.botgg.app/mcp",
"headers": { "Authorization": "Bearer botgg_…" }
}
}
}同意畫面
用戶端登入時,BotGG 會顯示是誰在要求存取,以及之後會把你導回哪裡。應用程式是自行註冊的,所以名稱並未經過驗證,請只同意你自己發起的連線。
- 用 Discord 登入(如果你還沒登入控制台)。
- 選擇一個伺服器。 只會列出你擁有「管理伺服器」權限的伺服器,而且你選的伺服器必須已加入 BotGG。每個連線永遠只屬於一個伺服器。
- 選擇權限。 這些與 API 金鑰使用的權限範圍相同。敏感的權限(對成員執行操作、管理資料)預設不會勾選,勾選時需要額外確認。
- 同意或拒絕。 應用程式會取得一個短效的存取權杖(1 小時),以及每次使用都會更換的更新權杖。
每個連線都會列在控制台的 伺服器 → 已連接的應用程式 之下,並顯示它的權限、是誰連接的,以及最後使用的時間。伺服器的任何管理者都可以在那裡中斷連線,應用程式會立即失去存取權。如果連接應用程式的人失去了「管理伺服器」權限,應用程式的存取權會在下一次呼叫時自動終止。
工具
每個 REST API 端點都對應一個工具,例如 bank.getBalance 會變成工具 bank_get_balance。輸入內容是該端點的路徑、查詢與內容欄位;伺服器 ID 不需要輸入,會直接取自連線。工具清單一律與 API 參考文件一致,而且用戶端只會看到其連線擁有對應權限範圍的工具。
- 唯讀的工具會有對應標示;會更改或移除資料的工具則標示為具破壞性,並且會要求助理先向你確認確切的操作內容。
- 每次呼叫都與 REST API 走同一條流程:權限範圍與功能檢查、資料驗證、錯誤代碼,以及該連線所屬方案的速率限制(API 金鑰在 REST 與 MCP 之間共用同一份額度)。
- 錯誤會以工具結果的形式回傳,使用與 REST API 相同的
error代碼,讓助理能自行說明或修正。 - 透過 MCP 所做的變更,會連同應用程式名稱寫入伺服器的稽核日誌。
| 範圍 | 允許的操作 |
|---|---|
guild:read | 讀取伺服器資訊 — 伺服器名稱、圖示、成員數、語言與已啟用的功能;身分組、頻道與基本成員資訊(身分組、暱稱、加入日期)。 |
bank:read | 讀取銀行 — 餘額、成員的交易紀錄與排行榜。 |
bank:write | 變更餘額 — 為成員增加或扣除貨幣。每次變更都會寫入銀行帳本。 |
levels:read | 讀取等級 — 成員的等級、經驗值與排名,以及經驗值排行榜。 |
levels:write | 變更經驗值 — 增加、扣除或設定成員的經驗值。獎勵身分組與升級公告的運作方式與 /levels 指令相同;每次變更都會記錄在稽核日誌。 |
invites:read | 讀取邀請 — 成員的邀請數與排名,以及邀請排行榜。 |
invites:write | 變更額外邀請數 — 增加或移除額外邀請數,如同 /invites add。里程碑獎勵會隨之發放;每次變更都會記錄在稽核日誌。 |
shop:read | 讀取商店 — 商店、商品、成員的背包與購買紀錄。 |
shop:write 敏感 | 管理商店 — 替成員購買商品(從其銀行餘額扣款,並給予身分組)、免費發放商品、退款、補貨,以及啟用或停用商品。 |
giveaways:read | 讀取抽獎 — 進行中與已結束的抽獎,包含參加人數、得獎者與參加者名單。 |
giveaways:write | 管理抽獎 — 開始抽獎、提前結束與重新抽出得獎者。機器人會在 Discord 發布並更新抽獎。 |
flows:read | 讀取流程 — 流程清單(名稱、開/關、觸發條件)以及執行的狀態與結果。 |
flows:run 敏感 | 執行流程 — 以你自己的輸入執行以「手動」或 Webhook 觸發條件開始的已啟用流程。流程會執行它的所有步驟;執行次數計入方案的每日上限。 |
tickets:read | 讀取客服單 — 客服單清單與詳細資料(開單者、面板、狀態、表單回答),以及已關閉客服單儲存的對話紀錄。 |
tickets:write | 關閉客服單 — 附上原因關閉未結案的客服單——機器人會儲存對話紀錄、寫入日誌並通知開單者,就像管理員關閉一樣。 |
applications:read | 讀取申請 — 申請表單與提交內容,包含申請者的回答、投票與決定。 |
applications:write | 決定申請 — 錄取或拒絕待處理的申請。機器人會給予/移除表單的身分組、私訊申請者,並像管理員做決定一樣更新審核。 |
appeals:read | 讀取停權申訴 — 停權申訴及其回答、停權原因與對話內容(絕不包含內部管理員備註)。 |
appeals:write 敏感 | 決定停權申訴 — 附上原因核准(解除停權)或駁回待處理的停權申訴;機器人會像管理員做決定一樣解除停權並私訊。 核准申訴會解除該成員的停權。 |
moderation:read 敏感 | 讀取管理案件 — 管理案件(警告、禁言、踢出、停權……)及其原因、證據連結與處理的管理員,以及 API 操作的狀態。 會公開成員的管理紀錄。 |
moderation:write 敏感 | 管理成員 — 以金鑰建立者的身分警告、禁言、踢出、停權與解除停權成員:僅限建立者仍擁有對應的 Discord 權限時、僅限身分組低於建立者與機器人最高身分組的成員、必須附上原因,每分鐘最多 10 次操作。 任何持有此金鑰的人都能以你的名義處罰成員。請妥善保密,不使用時請撤銷。 |
限制
| 項目 | 限制 |
|---|---|
| 每個連線的工具呼叫 | 方案的 API 每分鐘速率限制:Free 60,Pro 600 |
| 其他 MCP 請求(列出工具、握手) | 每個連線每分鐘 300 次 |
| 存取權杖/更新權杖 | 1 小時/30 天,每次更新都會續期 |
| 請求大小 | 每則 MCP 訊息 64 KB;每個工具的內容 8 KB,與 REST API 相同 |
安全
- 具破壞性操作的確認,是由你的 AI 應用程式依據工具標示來進行的,BotGG 看不到你的對話。請在用戶端中保持開啟確認功能。
- 透過 MCP 的寫入呼叫不使用
Idempotency-Key,所以助理不應該盲目重複失敗的寫入,請先檢查結果。需要自動化且可重試的寫入,請使用 REST API。 - 權杖綁定這個伺服器網址與單一 Discord 伺服器;BotGG 只儲存它們的雜湊值。如果更新權杖被重複使用,為了安全起見會中斷應用程式的連線,重新連接即可。
疑難排解
| 回應 | 處理方式 |
|---|---|
401 並帶有 error="invalid_token" | 權杖已過期、被撤銷,或應用程式已中斷連線,請從用戶端重新登入。 |
403 並帶有 error="insufficient_scope" | 連線缺少 scope 中指定的權限。請重新連接,並在同意畫面中勾選該權限。 |
403「Origin not allowed」 | 以瀏覽器為基礎的用戶端必須來自允許的 origin;桌面與伺服器端的用戶端不會傳送 Origin。 |
工具結果 BANK_DISABLED/FEATURE_DISABLED | 請在控制台中為該伺服器開啟這個功能。 |
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://console.botgg.app/.well-known/oauth-protected-resource/mcp"HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer resource_metadata="…", error="insufficient_scope", scope="bank:write"