Skip to main content
Glama
README.md
# discord-cli

**English** | [Português (Brasil)](./README.pt-BR.md)

Discord CLI (user token) and MCP server with **no dependencies**, built on the
`discord-userdoccers` documentation. Ships with the `discord-cli` binary and
output in **English, Portuguese (pt-BR), French and Spanish**.

> ⚠️ Uses a **user token**, which is against Discord's ToS when used for
> automation. Use a secondary account and at your own risk.

## Install

```bash
npm install -g discord-cli

# or run straight from the repo
node bin/discord-cli.js help
```

Requires Node.js >= 18.

## Quick start

```bash
discord-cli login --token <YOUR_TOKEN>   # stores the token in ~/.config/discord-cli/config.json
discord-cli whoami
discord-cli guilds
discord-cli channels <guild-id>
discord-cli read <channel-id> --limit 50
discord-cli send <channel-id> "hello from the terminal"
```

The token is also read from `DISCORD_TOKEN`, and the config file is written
with `0600` permissions.

## Languages

The CLI, the error messages and the MCP tool descriptions are translated.
Supported locales: `en`, `pt-BR`, `fr`, `es`.

Resolution order (first match wins):

1. `DISCORD_LOCALE` environment variable
2. `--lang <locale>` (or `--lang=<locale>`)
3. `lang` saved in the config file
4. `LC_ALL` / `LANG`
5. `en`

```bash
discord-cli --lang fr help          # French help
discord-cli lang pt-BR              # persist the language
discord-cli lang                    # show the current language + supported list
DISCORD_LOCALE=es discord-cli help   # per-invocation override
```

Accents are optional in input: `fr-FR`, `pt_BR.UTF-8`, `en_US`, `es-419` are
normalized automatically.

## Commands

| Command | Description |
| --- | --- |
| `login --token <TOKEN>` | Save the token and validate it |
| `whoami` / `me` | Show the authenticated user |
| `me edit --name <name>` | Change `global_name` |
| `sessions` / `logout` | List sessions / end the current one |
| `user <id>` | Fetch a user |
| `profile <id> [--guild-id <id>]` | Full profile |
| `notes <id> --set "text"` | Set a user note |
| `guilds` / `guild <id>` | List guilds / guild info |
| `channels <guild-id>` | List guild channels |
| `members <guild-id> [--query] [--limit]` | Members or member search |
| `search <guild-id> --query <text>` | Search messages in a guild |
| `dms` / `dm <user-id>` | List DMs / open a DM |
| `read <channel-id> [--limit] [--before] [--after]` | Read messages |
| `send <channel-id> "text" [--reply <msg-id>]` | Send a message |
| `editmsg <channel-id> <msg-id> "text"` | Edit a message |
| `delmsg <channel-id> <msg-id>` | Delete a message |
| `find <channel-id> --query <text>` | Search messages in a channel |
| `listen [--channels a,b] [--guild <id>]` | Live gateway events |
| `gateway` | Gateway info |
| `lang [<locale>]` | Show or set the language |
| `mcp [--lang <locale>]` | Start the MCP server on stdio |

Global flags: `--lang`, `--verbose`, `--json`, `--help`, `--version`.

Output is JSON by default, so it pipes cleanly into `jq`:

```bash
discord-cli guilds | jq '.guilds[].name'
```

## MCP server

The MCP server speaks JSON-RPC 2.0 over stdio and needs no dependencies.
Tool **descriptions** and protocol errors follow the active locale, so a
French-speaking model gets French descriptions.

Register it with Claude Desktop / any MCP client:

```json
{
  "mcpServers": {
    "discord": {
      "command": "discord-cli",
      "args": ["mcp", "--lang", "en"],
      "env": { "DISCORD_TOKEN": "your-user-token" }
    }
  }
}
```

Tools: `whoami`, `list_guilds`, `list_channels`, `list_dms`, `read_messages`,
`send_message`, `get_user`, `search_messages`.

`initialize` also reports `locale` and `supportedLocales`, and honours a
`clientInfo.locale` hint.

## Development

```bash
npm run lint    # syntax check + i18n key parity across locales
npm test        # node:test suite (i18n, CLI, MCP)
npm run check   # lint + tests, what CI runs
```

Adding a language = adding one object to `CATALOGS` in `src/i18n.js` (plus the
tool strings in `src/i18n-tools.js`). `npm run lint` fails if any locale is
missing a key.

## License

MIT — see [LICENSE](./LICENSE).