# GuildControl MCP server

> Lets an AI client read Discord guild data and perform reviewed, audited administrative actions through an operator-owned bot.

- Repository: https://github.com/j-256/guildcontrol
- Page: https://hostedmcp.org/servers/j-256/guildcontrol
- Transport: stdio
- Stars: 1
- License: AGPL-3.0
- Latest version: 2.3.9

## Install

### Claude Code

```sh
claude mcp add --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' guildcontrol -- npx -y guildctl
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "guildcontrol": {
      "command": "npx",
      "args": [
        "-y",
        "guildctl"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "guildcontrol": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "guildctl"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"guildcontrol","type":"stdio","command":"npx","args":["-y","guildctl"],"env":{"DISCORD_BOT_TOKEN":"<YOUR_DISCORD_BOT_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "guildcontrol": {
      "command": "npx",
      "args": [
        "-y",
        "guildctl"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add guildcontrol --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' --env 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' -- npx -y guildctl
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.guildcontrol]
command = "npx"
args = ["-y", "guildctl"]

[mcp_servers.guildcontrol.env]
DISCORD_BOT_TOKEN = "<YOUR_DISCORD_BOT_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' -e 'DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>' guildcontrol npx -- -y guildctl
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "guildcontrol": {
      "command": "npx",
      "args": [
        "-y",
        "guildctl"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "<YOUR_DISCORD_BOT_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `DISCORD_BOT_TOKEN` | yes | yes | Discord bot token sent only to fixed Discord REST and vetted Gateway origins |
| `DISCORD_BOT_TOKEN` | yes | yes | Discord bot token sent only to fixed Discord REST and vetted Gateway origins |

## FAQ

### How do I install and set up GuildControl MCP for Discord?

Run `npx guildctl` for interactive onboarding, or pass flags like --host, --application-id, and --guild-id for unattended setup. It creates a strict policy file and verifies the bot without storing the token.

### Does GuildControl need Discord Administrator permissions?

No. It recommends a least-privilege Read-only preset like server-observer and instructs you to narrow the bot role further.

### Where is the Discord bot token stored?

The token stays in a secret source you control, such as an environment variable or a token file mounted by your launcher; GuildControl stores only a credential reference.

### Does GuildControl store Discord message content?

No. It does not persist Discord content, and the default preset does not enable Message Content access.

### Can I migrate from another Discord MCP server?

Yes. `guildctl migrate plan` maps tools from an audited source release into supported, review-required, or excluded outcomes without changing anything.
