discord
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).