AIクライアントがDiscordギルドのデータを読み取り、オペレーター所有のボットを通じて、レビューおよび監査済みの管理アクションを実行できるようにします。
別名 j-256/guildcontrol, guildcontrol, guildctl
- スター
- 1
- ツール
- —
- ダウンロード数(30日間)
- 1,442
- 最新バージョン
- 2.3.9
- 最終コミット
- 2026年11月14日
- ライセンス
- AGPL-3.0
GuildControl MCPとは
AIクライアントがDiscordギルドのデータを読み取り、オペレーター所有のボットを通じて、レビューおよび監査済みの管理アクションを実行できるようにします。
プロジェクトのREADMEから生成された概要
GuildControl MCP server について
Discordの管理者や開発者は、GuildControl MCPを使用することで、AIクライアントからサーバーを管理できます。このローカルstdioサーバーは、オペレーター所有のボットを介してDiscordギルドに接続し、ギルドデータの検査や管理アクションの実行を可能にします。最小権限の原則に基づいて設計されており、ユーザーはDiscord Developer Portalを通じて独自のボットをセットアップし、環境変数または保護されたファイル経由でトークンを提供する必要があります。
このシステムは、レビュー済みの書き込みとプライバシーを重視した厳格なセーフティモデルによって差別化されています。広範な管理者権限を付与する代わりに、server-observerのようなプリセットを利用して、メッセージ内容へのアクセスを有効にすることなく、メタデータや権限の診断へのアクセスを制限できます。すべての変更(mutation)は、結果が検証可能であることを保証するために、署名付きの対話的な承認と最終的なプランの一致を必要とします。サーバーはDiscordの内容、プロフィール、または生の操作キーを永続化せず、機密データを呼び出し側が所有するシークレットソース内に保持します。
できること
- 1サーバー権限の監査AIがロールや権限の診断を検査し、サーバー設定が正しいことを確認できます。
- 2レビュー済みの管理アクションの実行生成されたプランを確認し、対話的な承認を行うことで、ギルドへの変更を実行できます。
- 3サーバーチャンネルのインベントリ作成開発者はこのサーバーを使用して、特定のギルド内の利用可能なチャンネルのリストを生成できます。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
GuildControl MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude CodeにGuildControl MCPをインストール
$ claude mcp add --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' guildcontrol -- npx -y guildctlCursorにGuildControl MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"guildcontrol": {
"command": "npx",
"args": [
"-y",
"guildctl"
],
"env": {
"DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
}
}
}
}VS CodeにGuildControl MCPをインストール
.vscode/mcp.json
{
"servers": {
"guildcontrol": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"guildctl"
],
"env": {
"DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
}
}
}
}VS Code CLIにGuildControl MCPをインストール
$ code --add-mcp '{"name":"guildcontrol","type":"stdio","command":"npx","args":["-y","guildctl"],"env":{"DISCORD_BOT_TOKEN":"<YOUR_DISCORD_BOT_TOKEN>"}}'Claude DesktopにGuildControl MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"guildcontrol": {
"command": "npx",
"args": [
"-y",
"guildctl"
],
"env": {
"DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
}
}
}
}CodexにGuildControl MCPをインストール
$ codex mcp add guildcontrol --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' -- npx -y guildctlCodex config.tomlにGuildControl MCPをインストール
~/.codex/config.toml
[mcp_servers.guildcontrol] command = "npx" args = ["-y", "guildctl"] [mcp_servers.guildcontrol.env] DISCORD_BOT_TOKEN = "<YOUR_DISCORD_BOT_TOKEN>"
Gemini CLIにGuildControl MCPをインストール
$ gemini mcp add -s user -e 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' -e 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' guildcontrol npx -- -y guildctlGemini settings.jsonにGuildControl MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"guildcontrol": {
"command": "npx",
"args": [
"-y",
"guildctl"
],
"env": {
"DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
}
}
}
}設定
DISCORD_BOT_TOKEN必須シークレットDiscord bot token sent only to fixed Discord REST and vetted Gateway origins
DISCORD_BOT_TOKEN必須シークレットDiscord bot token sent only to fixed Discord REST and vetted Gateway origins
| 名前 | 説明 | 種類 |
|---|---|---|
| DISCORD_BOT_TOKEN | Discord bot token sent only to fixed Discord REST and vetted Gateway origins | 必須シークレット |
| DISCORD_BOT_TOKEN | Discord bot token sent only to fixed Discord REST and vetted Gateway origins | 必須シークレット |
自動チェック
実行日 2026年11月12日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能合格
- オープンソースライセンス (OSI)合格
- 過去1年以内にコミットまたはリリースあり合格
- パッケージ名が有名なパッケージに酷似していない合格
- リモートエンドポイントがHTTPSを使用未チェック
- 破壊的なツールがラベル付けされている未チェック
- モデルへの隠れた指示がない合格
- パッケージおよびその依存関係に重大な勧告なし合格
README
GitHubで見るGuildControl MCP
GuildControl MCP is a local stdio Model Context Protocol server for safe Discord guild and separately allowlisted one-to-one access through an operator-owned bot. It combines broad typed coverage with exact scope, privacy-minimized results, reviewed writes, content-free evidence, and explicit ambiguity handling.
Least privilege. Review before mutation. Verifiable outcomes. No Discord-content persistence.
Documentation portal | Verified product tour | Get a verified read | Safety and usability decisions | Switch from another MCP | Fit and boundaries | Field comparison | Complete reference | Privacy | Security
GuildControl is an independent project and is not affiliated with or endorsed by Discord Inc. Discord is used only to identify the platform that GuildControl connects to.
Why this connector
| Concern | Enforced behavior |
|---|---|
| Discord reach | One strict non-secret policy file with verified application and bot identities, explicit guild and channel scope, a separate exact-user private-message scope, risk-separated toolsets, and read-only setup presets |
| Exact targeting | Canonical Discord jump links and official typed mentions convert locally into exact IDs without name lookup, Discord contact, input echo, persistence, or downstream authority |
| Read safety | Bounded requests, safe transient GET retries, lossless whole-result byte budgets, strict response validation, privacy-tiered projections, untrusted-content handling, caller-retained catch-up, exact attachment reads without local-file persistence, no private-channel discovery, and only explicit verified parent-thread inheritance |
| Write safety | Exact-ID requests, execute-first keyed planning, signed interactive approval, a final fresh-plan match, and action-specific Discord permission proof |
| Outcome integrity | Pending content-free evidence, non-retried writes, exact readback, durable coordination, ambiguity quarantine, and bounded local invalid-request pressure |
| Privacy | Tokens stay in a caller-owned secret source; Discord content, profiles, URLs, audit reasons, and raw operation keys are not persisted |
| Plan review | Complete evidence, MCP App display, and local authority-free blueprint preview |
| Release integrity | Exact dependency and base-image pins, credential-free contract fingerprints, reproducible npm and MCPB artifacts, hardened OCI checks, embedded and external SPDX evidence, signed-release automation, and source-bound public documentation |
Use the first verified read guide for setup and recovery. Read product boundaries and host compatibility before adopting the custody, privacy, approval, and recovery model. The complete reference covers every policy, tool, permission, resource, prompt, command, and workflow limit.
Quick start
The fastest supported outcome is an owner-managed read-only bot, one strict non-secret policy, one private host guide, and a successful channel inventory. You need Node.js 22.15 or newer, Manage Server authority in a Discord server you control, and a local stdio MCP host. GuildControl provides no shared bot, relay, or token store.
Guided setup: start here
Create an application and bot in the Discord Developer Portal, enable Developer Mode in Discord, and copy the Application ID and target Server ID. Then run:
npx guildctl
npx guildctl starts interactive onboarding: host selection, minimum server-observer policy creation or exact revalidation, live bot and MCP verification, and a private activation guide. It fails closed on drift and never stores the token, reads message content, enables writes, discovers host paths, or edits host configuration.
The result explains credential handoff; a one-time prompt is cleared after smoke. See the first verified read guide for custody and recovery.
Optional guildctl host detect checks path metadata only. onboard --detect-host selects one candidate; ambiguity requires a choice. Detection reads no candidate content or credential.
For unattended setup, supply every public decision and an existing secret reference:
npx --yes guildctl@2.3.7 onboard \
--host codex \
--application-id YOUR_APPLICATION_ID \
--guild-id YOUR_GUILD_ID \
--config /absolute/private/guildcontrol.json \
--confirm-installed YOUR_GUILD_ID \
--token-env DISCORD_BOT_TOKEN \
--json
JSON mode never prompts or opens a browser. The first verified read guide covers supported hosts, default paths, alternate credential custody, the manual route, and recovery.
Do not grant the bot Administrator. Generate the exact initial permission grant from a read-only preset, then narrow the installed bot role with category or channel overrides. The bot setup guide explains bot ownership, optional intents, and later feature-specific permissions.
Optional preflight: inspect without credentials
Inspect an exact release and its read-only preset without a token or Discord request:
npx --yes guildctl@2.3.7 catalog --check
npx --yes guildctl@2.3.7 catalog --html ./guildcontrol-contract.html
npx --yes guildctl@2.3.7 preset show server-observer
catalog --check verifies the credential-free, execution-disabled production contract, including complete per-tool setup and readiness metadata. catalog --html FILE renders it as a release-exact guided, searchable offline explorer with no external asset, runtime request, credential, or configured completion ID.
Switch from another Discord MCP
Generate a complete release-exact outcome map before creating policy or changing the old deployment:
npx --yes guildctl@2.3.7 migrate list
npx --yes guildctl@2.3.7 migrate plan cappyeo@0.31.1 --html ./guildcontrol-migration.html
The migration guide covers every scored peer release. Planning scans no checkout, reads no configuration, host setting, environment value, or credential, contacts no network or Discord endpoint, and changes nothing. It maps every audited source tool into supported, review-required, or intentionally excluded outcomes and validates target routes against the negotiated production catalog. It does not rewrite prompts, arguments, configuration, credentials, or host settings.
Install your owner-managed bot
Create a Discord application and bot in the Developer Portal, copy the public Application ID and target Server ID, and generate a callback-free install link whose guild and least-privilege permission grant come from the recommended preset:
npx --yes guildctl@2.3.7 preset install server-observer \
--application-id YOUR_APPLICATION_ID \
--guild-id YOUR_GUILD_ID \
--html ./guildcontrol-onboarding.html
Open the printed URL while signed in as a member allowed to manage that server. It requests only View Channel for server-observer, locks the server selector to the supplied ID, requests no user token, and never sends the bot token to the connector command. Keep Public Bot disabled unless other people should be able to install your application. Use channel-reader instead to request View Channel plus Read Message History; its plan also identifies Message Content as the recommended Developer Portal intent.
Optional --html FILE adds a deterministic standalone checklist, copy controls, explicit Discord navigation, pinned follow-up commands, and exact plan evidence without a token, external asset, background request, persisted browser state, automatic browser launch, or overwrite. The terminal plan remains complete without HTML.
Create the safest first configuration
From a canonical process-owned private directory, keep the token in a secret-capable launching environment, verify one exact guild, save the complete non-secret policy in one file, and test the full MCP path:
export DISCORD_BOT_TOKEN
printf 'Discord bot token: '
read -r -s DISCORD_BOT_TOKEN
printf '\n'
npx --yes guildctl@2.3.7 setup \
--npx \
--config ./guildcontrol.json \
--preset server-observer \
--guild-id YOUR_GUILD_ID
npx --yes guildctl@2.3.7 host --npx --config ./guildcontrol.json --html ./guildcontrol-host-activation.html
On PowerShell 7.1 or newer, read the token into the current process without displaying it or placing its value in command history, then run the same commands:
$env:DISCORD_BOT_TOKEN = Read-Host "Discord bot token" -MaskInput
Enter each displayed multi-line shell command on one line in PowerShell; the npx arguments remain the same. With older Windows PowerShell, use an MCP host secret facility or protected token file instead of a token literal in command history.
If the launcher, container runtime, or orchestrator mounts the token as a file, select that input instead. The path must be absolute, the file must already exist for verified setup, and --token-file cannot be combined with --token-env or an ambient DISCORD_BOT_TOKEN:
npx --yes guildctl@2.3.7 setup \
--npx \
--config ./guildcontrol.json \
--preset server-observer \
--guild-id YOUR_GUILD_ID \
--token-file /run/secrets/discord_bot_token
The server-observer preset exposes guild metadata, roles, permission diagnostics, connector health, content-free activity, and tool discovery without enabling writes, the Gateway, telemetry, persistence, or Message Content access. Setup is the first-run readiness gate: it validates the strict policy, verifies the application and bot, audits the exact guild installation, stores public IDs and a credential reference but never the token, and prints the launch descriptor. A ready setup exits successfully even when it reports non-blocking warnings for deliberate review. route_discord_goal safely routes later discovery, reads, and reviewed planning, never mutation; it creates bookkeeping keys itself instead of asking the operator to invent them.
The versioned file is the only policy boundary. It covers identity, explicit read modes, typed reusable exact-ID groups, notification and thread behavior, tools, capabilities, scopes, limits, storage, Gateway, runtime, and observability. A typical deployment has one JSON policy and one external bot-token secret. The JSON Schema, config show, and config explain support secret-free inspection; managed profiles use the same document.
Operational commands require --config FILE, --profile NAME, or the non-secret GUILDCONTROL_CONFIG_FILE selector. Ambient policy variables are rejected and there is no alternate environment-policy or automatic import mode. The offline migrate planner never becomes a runtime policy source. Running setup without a preset verifies an existing policy without rewriting it, while a preset explicitly creates or replaces the selected target.
Connect with the one-click bundle or a generated adapter
After setup reports ready, compatible MCPB hosts can import guildcontrol-2.3.7.mcpb from the immutable GitHub Release or MCP Registry. Select the strict config and enter only the token through the sensitive prompt. The verified bundle supports macOS, Windows, and Linux, duplicates no policy field, embeds privacy and dependency evidence, and completes a real unpacked MCP handshake.
For a file-backed token or another host, host emits deterministic adapters for Claude Code, Codex, Cursor, VS Code, Gemini CLI, and common MCP JSON. Optional host detect reports plausible hosts from metadata only. host plan and host apply review and install one static JSON projection without resolving credentials or replacing unrelated entries; Codex receives an exact reviewable TOML projection, and --inspect-host-file reports exact JSON drift without returning observed values. The connection guide covers setup and verification.
Once the host is connected, the first useful request can stay natural and narrow:
Show me the channels in Discord server YOUR_GUILD_ID using GuildControl MCP. Do not make changes.
config validate, doctor, and smoke are optional assurance and recovery tools after successful setup. Offline doctor can inspect policy without an available credential; --online contacts Discord only when it is available, while smoke verifies a child MCP handshake. Human doctor output shows actionable warnings and failures; add --verbose for every check or --json for complete evidence. Doctor exits 1 for warnings, including ready with warnings.
npx --yes guildctl@2.3.7 config validate ./guildcontrol.json
npx --yes guildctl@2.3.7 doctor --config ./guildcontrol.json --online
npx --yes guildctl@2.3.7 smoke --config ./guildcontrol.json
Review any policy replacement
Keep the active policy unchanged while editing a separate candidate, then use the integrated review path:
npx --yes guildctl@2.3.7 config workbench \
./guildcontrol.json \
--html ./guildcontrol-workbench.html
npx --yes guildctl@2.3.7 config replace \
./guildcontrol.json \
./guildcontrol.candidate.json
config replace prints the plan before named confirmation, recomputes under lock, writes atomically, keeps a backup, and verifies the result. Detached review remains available:
npx --yes guildctl@2.3.7 config plan \
./guildcontrol.json \
./guildcontrol.candidate.json
npx --yes guildctl@2.3.7 config apply \
./guildcontrol.json \
./guildcontrol.candidate.json \
--plan-digest SHA256_FROM_THE_PLAN \
--confirm ACTIVE_POLICY_NAME
The private workbench keeps edits in memory until explicit candidate download and has no secret, network, persistence, Discord, active-file write, or approval authority. Both application paths reread the files, reject identity or file drift, and preserve a recoverable backup. The active document remains the only policy source.
Review recent write outcomes and durable cross-process claims from the same selected policy without making a Discord request or resolving its credential:
npx --yes guildctl@2.3.7 activity \
--config ./guildcontrol.json \
--html ./guildcontrol-activity.html
The bounded review collapses each activity into its newest outcome, retains superseded history, joins durable claims only through content-free digests, and warns on every unsettled state. Its optional private explorer adds search and filters but cannot contact Discord, resolve a claim, retry an operation, or persist browser state. Use coordination resolve only after stopping the owner and checking the exact Discord state and audit log.
Feature policy uses the same document shape. Reviewed features retain separate capabilities, exact scopes, bounded limits, and documented toolsets; single-member authority never grants batch authority. No environment-policy interface, legacy alias, fallback parser, or automatic migration layer exists.
Use channel-reader only when bounded message history, caller-retained channel catch-up, and native search are needed. It requires at least one exact channel:
npx --yes guildctl@2.3.7 setup \
--npx \
--config ./discord-reader.json \
--preset channel-reader \
--guild-id YOUR_GUILD_ID \
--channel-id YOUR_CHANNEL_ID
Expand the policy through review
Keep first setup read-only, then enable one additive recipe through integrated review. message-channel is the narrowest first write: plain sends, replies, connector-owned edits in exact channels or eligible child threads, and exact-target typing. coordination-channel adds directed notes; channel-publisher adds broader publishing; guild-starter adds reviewed public layouts with nonprivileged GUILDS evidence; guild-builder adds blueprint lifecycle; incident-response adds lockdown; and direct-messenger adds exact-user private messaging. Every recipe reports permissions, intents, scopes, risks, and exclusions.
npx --yes guildctl@2.3.7 recipe list
npx --yes guildctl@2.3.7 recipe enable message-channel ./guildcontrol.json \
--channel-id YOUR_MESSAGE_CHANNEL_ID
npx --yes guildctl@2.3.7 recipe enable direct-messenger ./guildcontrol.json \
--user-id EXPECTED_RECIPIENT_USER_ID
npx --yes guildctl@2.3.7 recipe enable guild-starter ./guildcontrol.json \
--guild-id YOUR_GUILD_ID
The detached automation path remains explicit:
npx --yes guildctl@2.3.7 recipe plan guild-starter ./guildcontrol.json \
--guild-id YOUR_GUILD_ID
npx --yes guildctl@2.3.7 recipe apply guild-starter ./guildcontrol.json \
--guild-id YOUR_GUILD_ID \
--plan-digest SHA256_FROM_THE_PLAN \
--confirm guild-starter
Both paths show the complete policy delta, requirements, risks, warnings, and path-bound evidence without a secret or Discord request. Application recomputes, requires name confirmation, rejects drift, and keeps a backup. Recipes grant no Discord authority.
Online doctor verifies identity, complete ID-only installation drift, and application posture. Smoke launches serve, negotiates stable MCP over stdio, validates catalogs and read-only status, writes nothing to Discord, and shuts down configured runtimes. See the operator reference.
Build from source
git clone https://github.com/j-256/guildcontrol.git
cd guildcontrol
npm run deps:locked
npm run build
node dist/bin.js catalog --check
The exact installation, operator CLI, and configuration references cover standalone configuration, managed profiles, OCI bind mounts, progressive discovery, toolsets, allowlists, optional Gateway modes, observability, and every independently gated feature.
Capability map
| Area | Selected capabilities |
|---|---|
| Discovery and reads | Scoped guild, channel, message, thread, forum, member, moderation, audit, application, event, voice, and configuration reads; exact-ID parsing and attachment access; caller-retained multi-channel catch-up, native search, bounded recall, aggregate activity, and privacy-minimized outputs |
| Messages and communities | Idempotent delivery; authority-free directed notes and exact-message task coordination; reviewed private messages; Components V2, remote-free embeds, attachments, reactions, polls, crossposts, forwarding, threads, pins, and exact deletion |
| Guild structure | Deterministic starters and caller-retained blueprints; additive channels, roles, forums, permissions, onboarding, AutoMod, and publications; reviewed cloning, ordering, metadata, synchronization, and retirement |
| Members and moderation | Privacy-minimized directories and ban audits; reviewed exact-member moderation, roles, nicknames, verification, voice, and thread membership; resumable batches, native bulk bans, and protected guild pruning |
| Community configuration | Application, command, linked-role, monetization, webhook, integration, invite, template, profile, settings, Community, expression, soundboard, event, Stage, and AutoMod audits and reviewed lifecycles |
| Operations | Progressive tool discovery and packaged documentation search; resources and prompts; model-neutral playbooks; strict configuration, profiles, host guides, presets, and recipes; content-free audit and coordination; bounded Gateway and native Interaction runtimes; OpenTelemetry diagnostics |
Capabilities are exposed only when their toolset and policy gates are selected. A toolset narrows the callable surface but never grants Discord or local write authority. Browse the exact tool reference, resources, and prompts.
GuildControl MCPのよくある質問
GuildControl MCPをClaude Codeに追加するには
ターミナルでclaude mcp add --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' guildcontrol -- npx -y guildctlを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
GuildControl MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
GuildControl MCPをDiscordにインストールして設定するにはどうすればよいですか?
npx guildctlを実行して対話形式のオンボーディングを行うか、--host、--application-id、--guild-idなどのフラグを指定して自動セットアップを行います。これにより、厳格なポリシーファイルが作成され、トークンを保存することなくボットの検証が行われます。
GuildControlにはDiscordのAdministrator権限が必要ですか?
いいえ。server-observerのような最小権限のRead-onlyプリセットの使用を推奨しており、ボットのロールをさらに絞り込むよう指示します。
Discordボットのトークンはどこに保存されますか?
トークンは、環境変数やランチャーによってマウントされたトークンファイルなど、ユーザーが管理するシークレットソースに保持されます。GuildControlは認証情報の参照のみを保存します。
GuildControlはDiscordのメッセージ内容を保存しますか?
いいえ。Discordの内容を永続化することはありません。また、デフォルトのプリセットではMessage Contentへのアクセスは有効になりません。
他のDiscord MCP serverから移行できますか?
はい。guildctl migrate planを使用すると、監査済みのソースリリースからツールをマッピングし、設定を変更することなく、サポート対象、レビュー必須、または除外対象の結果に分類できます。