Documentation

Everything you need to know about setting up and using RPCraft.

Quick Start

Get your Discord Rich Presence up and running in three steps.

1. Install

bash

$ git clone https://github.com/fxckcode/discord-rpc-tui.git
$ cd discord-rpc-tui
$ bash install.sh

2. Start the service

bash

$ systemctl --user start discord-rpc-tui

3. Verify it works

bash

$ rpc-tui set-activity '{"state":"Hello Discord!","type":0}'

Your Discord profile should now show "Playing Hello Discord!". If it doesn't, check the Troubleshooting section.

Setup Discord Developer Portal

To use custom images and your own application identity, you need to register an application on Discord's Developer Portal.

1.Open the Discord Developer Portal

Go to discord.com/developers/applications

2.Create a New Application

Click New Application and give it a name — this will be the name shown in your Discord presence.

3.Open the Rich Presence section

Navigate to Rich Presence in the left sidebar (or Artifacts depending on Discord's current UI layout). This is where you upload images for your presence.

4.Upload images

Click Add Image(s) and select your PNG, JPG, or GIF files. These images appear as the large or small icons in your Rich Presence.

5.Note the Asset Name

Discord assigns an Asset Name to each uploaded image (e.g., imagen, myimage). You'll use this name in your activity configuration as largeImageKey. Asset names are case-sensitive.

6.Copy your Application ID

Go to General Information and copy the Application ID (also called Client ID).

7.Set the Client ID in your config

Paste the Application ID into your config file at ~/.config/discord-rpc-tui/config.json.

Configuration

The config file at ~/.config/discord-rpc-tui/config.json controls everything about your Rich Presence. Here's the full structure:

json

{
  "clientId": "123456789012345678",
  "profiles": [
    {
      "name": "Coding",
      "activity": {
        "state": "Working on a feature",
        "details": "VS Code",
        "type": 0,
        "largeImageKey": "vscode",
        "largeImageText": "Visual Studio Code",
        "buttons": [
          { "label": "View Project", "url": "https://github.com/user/repo" }
        ]
      }
    }
  ],
  "rotationInterval": 30
}

clientId

Your Discord Application ID (step 6 above). Required.

profiles

An array of activity profiles that rotate if you set rotationInterval. Each profile has:

name — a label for the profile
activity — the Rich Presence payload with state, details, type, largeImageKey, buttons, and more

rotationInterval

Seconds between profile rotations. Set to 0 to disable rotation (stays on the current profile).

Activity type values

Value	Status	Example
0	Playing	Playing Minecraft
1	Streaming	Streaming on Twitch
2	Listening	Listening to Spotify
3	Watching	Watching a Movie
5	Competing	Competing in Valorant

Using Presences from the Gallery

The Gallery makes it simple to try out and apply Rich Presences. Here's how it works:

1.Browse the Gallery

Head to the Gallery page and browse through curated presences organized by category — Coding, Music, Gaming, Creative, and Social.

2.Click a presence card

Each card shows a preview of the activity. Click it to see the full detail page with all the configured fields.

3.Copy the command

On the detail page, you'll see a terminal command like this:

bash

$ rpc-tui set-activity '{
  "state": "Coding in TypeScript",
  "details": "VS Code",
  "type": 0,
  "largeImageKey": "vscode"
}'

Click Copy Command to copy it to your clipboard.

4.Run the command

Paste the command in your terminal and press Enter. The tool updates your config file automatically and restarts the service. Your Discord presence updates within seconds.

Troubleshooting

Connection failed

Make sure Discord is running on your system. discord-rpc-tui requires an active Discord client to establish the RPC connection.

Image not showing

Check that the asset name in your config matches exactly (including case) the name shown in the Discord Developer Portal. Asset names are case-sensitive — MyImage and myimage are different.

Service not running

If the systemd service isn't active, start it manually:

bash

$ systemctl --user start discord-rpc-tui

You can also check the service status with systemctl --user status discord-rpc-tui.

Permission denied

Make sure rpc-tui is in your PATH. Restart your shell after installation or add the install directory to your PATH manually in ~/.bashrc or ~/.zshrc.

AI Agent Integration (MCP)

RPCraft includes a Model Context Protocol (MCP) server that lets AI coding agents control your Discord Rich Presence programmatically. Your agent can set activities, switch profiles, and check connection status — all through natural language.

Start the MCP server

First, make sure the service is running, then start the MCP server:

bash

$ rpc-tui mcp

This starts the server in stdio mode — the default for CLI agents. For HTTP clients, use rpc-tui mcp --sse --port 3100.

Setup by agent

Hermes Agent

Add as an MCP server via the CLI:

bash

$ hermes mcp add rpcraft --command "rpc-tui mcp"
$ hermes mcp test rpcraft

Or add it to ~/.hermes/config.yaml:

json

mcp:
  servers:
    rpcraft:
      command: rpc-tui
      args: [mcp]

After adding, tell Hermes: "Set my Discord presence to Coding in TypeScript".

Claude Code

Add to your project's CLAUDE.md or global config:

json

{
  "mcpServers": {
    "rpcraft": {
      "command": "rpc-tui",
      "args": ["mcp"]
    }
  }
}

Claude Code discovers MCP tools automatically. Try: "Update my Discord status to show I'm coding".

Codex CLI / OpenCode

Add the MCP server in opencode.json:

json

{
  "mcpServers": {
    "rpcraft": {
      "command": "rpc-tui",
      "args": ["mcp"]
    }
  }
}

Both Codex CLI and OpenCode follow the same format.

Cursor

Add to .cursor/mcp.json:

json

{
  "mcpServers": {
    "rpcraft": {
      "command": "rpc-tui",
      "args": ["mcp"]
    }
  }
}

Cursor loads MCP servers from the project root automatically.

Gemini CLI

Configure via commands:

bash

$ gemini config set mcpServers.rpcraft.command rpc-tui
$ gemini config set mcpServers.rpcraft.args '["mcp"]'

Available MCP Tools

Tool	Description	Key params
set_activity	Set custom Rich Presence	state, details, type, largeImageKey
set_profile	Activate a saved profile	name
list_profiles	List saved profiles	—
get_status	Check connection status	—
connect	Connect to Discord RPC	—
disconnect	Disconnect from Discord	—

💡 Pro tip: Once the MCP server is configured, you can ask your agent things like "Set my Discord status to studying" or "Rotate between my coding and music profiles every 10 minutes" — and it just works.

Ready to try some presences?

Browse the Gallery