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)

  1. 開啟 Settings → Connectors,然後選擇 Add custom connector。
  2. 將它命名為 BotGG,並貼上 https://console.botgg.app/mcp 作為網址,然後按 Add。
  3. 按下 Connect:BotGG 會開啟,你用 Discord 登入並同意(請見同意畫面)。

ChatGPT

  1. 開啟 Settings → Apps & Connectors。自訂連接器需要在你的方案中啟用 Developer mode(位於 Advanced settings)。
  2. 選擇 Create,將它命名為 BotGG,貼上 https://console.botgg.app/mcp 作為 MCP 伺服器網址,並將驗證方式選為 OAuth。
  3. 建立連接器後,在 ChatGPT 開啟 BotGG 時登入。

Cursor

把伺服器加入 ~/.cursor/mcp.json(或專案的 .cursor/mcp.json)。Cursor 會在旁邊顯示 Needs login,點一下即可在瀏覽器中用 Discord 登入。

.cursor/mcp.json
{
  "mcpServers": {
    "botgg": { "url": "https://console.botgg.app/mcp" }
  }
}

Claude Code

Terminal
claude mcp add --transport http botgg https://console.botgg.app/mcp
# then run /mcp inside Claude Code and choose "Authenticate"

任何使用 API 金鑰的用戶端

MCP 用戶端設定(JSON)
{
  "mcpServers": {
    "botgg": {
      "type": "http",
      "url": "https://console.botgg.app/mcp",
      "headers": { "Authorization": "Bearer botgg_…" }
    }
  }
}

用戶端登入時,BotGG 會顯示是誰在要求存取,以及之後會把你導回哪裡。應用程式是自行註冊的,所以名稱並未經過驗證,請只同意你自己發起的連線。

  1. 用 Discord 登入(如果你還沒登入控制台)。
  2. 選擇一個伺服器。 只會列出你擁有「管理伺服器」權限的伺服器,而且你選的伺服器必須已加入 BotGG。每個連線永遠只屬於一個伺服器。
  3. 選擇權限。 這些與 API 金鑰使用的權限範圍相同。敏感的權限(對成員執行操作、管理資料)預設不會勾選,勾選時需要額外確認。
  4. 同意或拒絕。 應用程式會取得一個短效的存取權杖(1 小時),以及每次使用都會更換的更新權杖。

每個連線都會列在控制台的 伺服器 → 已連接的應用程式 之下,並顯示它的權限、是誰連接的,以及最後使用的時間。伺服器的任何管理者都可以在那裡中斷連線,應用程式會立即失去存取權。如果連接應用程式的人失去了「管理伺服器」權限,應用程式的存取權會在下一次呼叫時自動終止。

工具

每個 REST API 端點都對應一個工具,例如 bank.getBalance 會變成工具 bank_get_balance。輸入內容是該端點的路徑、查詢與內容欄位;伺服器 ID 不需要輸入,會直接取自連線。工具清單一律與 API 參考文件一致,而且用戶端只會看到其連線擁有對應權限範圍的工具。

  • 唯讀的工具會有對應標示;會更改或移除資料的工具則標示為具破壞性,並且會要求助理先向你確認確切的操作內容。
  • 每次呼叫都與 REST API 走同一條流程:權限範圍與功能檢查、資料驗證、錯誤代碼,以及該連線所屬方案的速率限制(API 金鑰在 REST 與 MCP 之間共用同一份額度)。
  • 錯誤會以工具結果的形式回傳,使用與 REST API 相同的 error 代碼,讓助理能自行說明或修正。
  • 透過 MCP 所做的變更,會連同應用程式名稱寫入伺服器的稽核日誌。
API 金鑰範圍
範圍允許的操作
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 次操作。
任何持有此金鑰的人都能以你的名義處罰成員。請妥善保密,不使用時請撤銷。

限制

MCP 限制
項目限制
每個連線的工具呼叫方案的 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"

常見問題

一個連線可以管理多個伺服器嗎?

不行。每個連線都綁定在你選擇的那一個伺服器。如果也想在另一個伺服器使用,請再次連接應用程式,並選擇那個伺服器。

誰可以查看並中斷已連接的應用程式?

伺服器的每一位管理者,可在控制台中該伺服器的「已連接的應用程式」頁面操作。

助理會取得我的 Discord 帳號嗎?

不會。它取得的是限定於單一伺服器、以及你所同意權限的 BotGG 權杖。你的 Discord 登入資訊仍由 BotGG 保管。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。