Use Murage from Claude Code, Codex and other AI apps
Hand a task to one of your bots from Claude Code, Codex or a script, wait for the result, and keep every approval in your own hands.
Make a token for one bot
Step 1
Switch on script access
Open SettingsDevices (it sits under Reach), open Advanced, and find Scripts and other apps. Switch on Let scripts use a bot. The card on the settings page is labelled Phone and other devices, but the page you want is Devices.
You're done when: the Scripts and other apps card shows Let scripts use a bot turned on.
Step 2
Pick the bot and what it may do
Pick one bot. Tick Also let it send messages to this bot if the other app should hand it work. Leave it unticked and the other app can only read and wait. Choose Create access.
You're done when: Create access is the next thing you press.
Step 3
Copy the token now
Murage shows the token once: "Copy this now. Murage shows it once." Murage keeps only a hash of it, so nobody can ask Murage for it again. If you lose it, switch that access off and make a new one.
You're done when: your access is listed with the bot's name, whether it reads or reads and sends, and the day it expires.
The token lasts 30 days. Switch off beside an access ends it at once, and you can hold up to 20 at a time.
Point your other app at Murage
Every app starts Murage's server the same way. It runs from inside the installed Murage app, so you do not need Node, pnpm or anything else on the computer.
| Computer | Command | Script argument |
|---|---|---|
| Mac | /Applications/Murage.app/Contents/MacOS/Murage | /Applications/Murage.app/Contents/Resources/server/mcp-server.js |
| Windows | %LOCALAPPDATA%\Programs\Murage\Murage.exe | resources\server\mcp-server.js, in the same folder |
| Linux (.deb install) | /opt/Murage/murage | /opt/Murage/resources/server/mcp-server.js |
Three environment values go with it: ELECTRON_RUN_AS_NODE set to 1, MURAGE_TOKEN set to your token, and MURAGE_PORT set to 8799. Murage normally listens on 8799. If another program already holds that port, Murage moves to 18799 or 28799, so set MURAGE_PORT to match. The port has to be named whenever a token is set, which keeps the token from being offered to any other program on your computer.
Claude Code
One command adds it for every project you open. The -- splits Claude Code's options from the command that starts Murage. On Windows and Linux, swap in the paths from the table.
claude mcp add murage --scope user \ --env ELECTRON_RUN_AS_NODE=1 \ --env MURAGE_PORT=8799 \ --env MURAGE_TOKEN=paste-your-token-here \ -- /Applications/Murage.app/Contents/MacOS/Murage \ /Applications/Murage.app/Contents/Resources/server/mcp-server.js
To share the setup with a team through a project's .mcp.json, keep the token out of the file. Claude Code fills ${MURAGE_TOKEN} from your shell when it starts.
{
"mcpServers": {
"murage": {
"command": "/Applications/Murage.app/Contents/MacOS/Murage",
"args": ["/Applications/Murage.app/Contents/Resources/server/mcp-server.js"],
"env": {
"ELECTRON_RUN_AS_NODE": "1",
"MURAGE_PORT": "8799",
"MURAGE_TOKEN": "${MURAGE_TOKEN}"
}
}
}
}
Run /mcp inside Claude Code and you should see murage connected.
Codex
Codex reads ~/.codex/config.toml, and that file is TOML, not JSON. Add this block, then start Codex again.
[mcp_servers.murage]
command = "/Applications/Murage.app/Contents/MacOS/Murage"
args = ["/Applications/Murage.app/Contents/Resources/server/mcp-server.js"]
env = { ELECTRON_RUN_AS_NODE = "1", MURAGE_PORT = "8799", MURAGE_TOKEN = "paste-your-token-here" }
That file is plain text, so treat it like a password file.
Cursor and other apps
Cursor reads ~/.cursor/mcp.json, which takes the same JSON as the .mcp.json above. Any other app that can launch a stdio MCP server needs the same three things: the command, the script argument and the three environment values.
What you can do with it
Say Claude Code is fixing a failing build and the bot "Ops" already holds the deploy notes. In Claude Code you ask it to send Ops the task and wait. It calls send_bot_message, then wait_for_conversation, and gets the bot's last few messages back when the bot finishes.
wait_for_conversation answers with one of five words:
settled, the bot finished.needs-user, the bot is waiting on a card only you can answer.failed, the turn ended in an error.stalled, the bot has gone quiet.timed-out, the wait ran out. It waits 30 seconds unless you ask for more, up to 120, and you can call it again.
A script can do the same on a timer to check how a bot is getting on. If the plan changes, interrupt_conversation stops the bot's current turn.
Which tools work with your one-bot token
A token for one bot opens the tools that read and drive that bot. Everything else belongs to the app on your desk, where you can see what is happening.
| Works with the token | What it does |
|---|---|
get_system_health | Confirms Murage is running and reachable. |
list_bots | Shows your one bot, with what it is doing right now. |
get_bot_messages | Reads its current conversation, up to 200 messages a page, with screenshot pictures left out. |
wait_for_conversation | Waits on that bot and returns settled, needs-user, failed, stalled or timed-out. Use it with the bot as the target. |
send_bot_message | Hands the bot a task. Needs the send box ticked. |
interrupt_conversation | Stops the bot's current turn. Needs the send box ticked. |
| Done in the Murage app | Tools |
|---|---|
| Search across conversations | search_messages |
| Rooms | list_channels, get_channel_messages, send_channel_message, create_channel, update_channel |
| Setting up bots | create_bot, update_bot_profile |
| Tasks | create_task, switch_task, rename_task |
| Models | set_bot_model, list_available_models |
These stay in the app on purpose. Opening a new task, picking a model or setting up a room are changes to your team, so you make them where you can see them. If a tool from the second table is called with a one-bot token, Murage answers that no such route exists, and the other app shows an error.
What it can't do
The token is built to do one job, which is to let another app work with one bot. That shapes what it leaves to you:
- Approvals stay yours. When the bot reaches a card that needs a yes,
wait_for_conversationreturnsneeds-user. You tap the answer in the app or on your paired phone, and the bot carries on. - Settings stay yours. The token cannot change a setting, a permission or a key. You do that in the app.
- One bot, nothing around it. Other bots, rooms and search are out of reach, so a mix-up in a script cannot wander into the rest of your team.
- It runs while Murage runs. Keep the app open on the computer the bot lives on. If Murage is closed, the other app has nothing to talk to.
- It runs out in 30 days. Make a new access when it does, and switch off any you no longer need.
Limits
- Murage must be running. The server talks to the desktop app on the same computer, usually on port 8799.
- One token, one bot. Make a second access for a second bot, up to 20 in all.
- 30 days. A token expires on the date shown beside it.
- Reading and waiting need no send box. Sending a task and stopping a turn do.
- Messages up to 100,000 characters. Reads come back 200 messages at a time.
- Keep the token private. Keep it out of shared files and out of a command typed where it will be saved.
If it does not connect
- The app says it cannot find Murage. Open Murage first, then restart the other app. Check
MURAGE_PORTmatches the port Murage is using. - Every tool says no such route. The token may have expired or been switched off, or the call is one that needs the app. Look at the list under SettingsDevices and make a new access if needed.
- Sending fails but reading works. The access was made without the send box. Make a new one with it ticked.