MCP Rocket.Chat Setup Guide

Rocket.Chat MCP server for Nanobot, Cursor, and Claude Desktop. Use it as:

• HTTP server (Docker) — no credentials in the container; clients (e.g. Nanobot) send credentials in request headers.
• Stdio — credentials from environment or CLI args.

Credentials

When using HTTP (recommended with Nanobot in Docker): the MCP server runs without credentials. Pass them in Nanobot’s config under mcpServers.<name>.headers; they are sent with every request. No .env or container env needed.

When using stdio or optional Docker defaults: use environment variables or CLI args.

Use either username/password or user ID + auth token (token takes precedence when both are set).

Source	Server URL	Username / Password	User ID / Auth Token
Headers	X-RocketChat-Server-URL or X-RocketChat-URL	X-RocketChat-Username, X-RocketChat-Password	X-RocketChat-User-Id, X-RocketChat-Auth-Token
Env	ROCKETCHAT_SERVER_URL or ROCKETCHAT_URL	ROCKETCHAT_USERNAME, ROCKETCHAT_PASSWORD	ROCKETCHAT_USER_ID, ROCKETCHAT_AUTH_TOKEN
CLI	--server-url	--username, --password	(not available)

---

Run as MCP inside Nanobot via HTTP (recommended)

The MCP server runs without credentials in the container. Credentials are sent by Nanobot on each request via headers.

1. Start the MCP server (no env vars or .env required):

   docker compose up -d
   

   It listens at http://<host>:3011/mcp.

2. Configure Nanobot (~/.nanobot/config.json): add the server with url and headers (credentials live only in your config):

   {
     "tools": {
       "mcpServers": {
         "mcp-rocketchat": {
           "url": "http://rocketchat-mcp:3011/mcp",
           "headers": {
             "X-RocketChat-Server-URL": "https://chat.example.com",
             "X-RocketChat-User-Id": "your-user-id",
             "X-RocketChat-Auth-Token": "your-auth-token"
           }
         }
       }
     }
   }
   

   Alternative — username/password (server will log in on first use):

   "headers": {
     "X-RocketChat-Server-URL": "https://chat.example.com",
     "X-RocketChat-Username": "your-bot-user",
     "X-RocketChat-Password": "your-password"
   }
   

   Use the hostname that reaches the MCP server from Nanobot (e.g. rocketchat-mcp if both are on the same Docker network, or host.docker.internal:3011 if the server runs on the host).

3. Restart Nanobot. Credentials are sent with every MCP request; nothing is stored in the container.

---

Run as MCP inside Nanobot (stdio)

Nanobot starts the server as a subprocess and talks over stdio. Credentials must be available as env vars where Nanobot runs.

1. Set environment variables (e.g. in your shell profile or where you start Nanobot). Use either username/password or user ID + auth token:

   export ROCKETCHAT_SERVER_URL="https://your-server.com"
   # Option A: username/password
   export ROCKETCHAT_USERNAME="your-bot-user"
   export ROCKETCHAT_PASSWORD="your-password"
   # Option B: user ID + auth token (instead of A)
   # export ROCKETCHAT_USER_ID="your-user-id"
   # export ROCKETCHAT_AUTH_TOKEN="your-auth-token"
   

2. Add the MCP server to Nanobot config (~/.nanobot/config.json):

   {
     "tools": {
       "mcpServers": {
         "rocketchat": {
           "command": "python",
           "args": ["/absolute/path/to/rocketchat.py"]
         }
       }
     }
   }
   

   Or with uv from the project directory:

   {
     "tools": {
       "mcpServers": {
         "rocketchat": {
           "command": "uv",
           "args": ["run", "--project", "/path/to/rocketchat-mcp", "rocketchat.py"]
         }
       }
     }
   }
   

3. Restart Nanobot (e.g. nanobot gateway). The RocketChat tools will be available to the agent.

No --transport or --server-url is needed: the server uses stdio by default and reads credentials from the environment.

---

Run with Cursor / Claude Desktop (stdio)

Same as Nanobot: use env vars for credentials and start the server with no --transport (stdio is default).

Example (credentials in args; avoid in shared environments):

{
  "mcpServers": {
    "rocketchat": {
      "command": "python",
      "args": [
        "C:/path/to/rocketchat.py",
        "--server-url", "https://your-server.com",
        "--username", "user",
        "--password", "pass"
      ]
    }
  }
}

Prefer setting credentials in the environment (ROCKETCHAT_SERVER_URL plus either username/password or ROCKETCHAT_USER_ID/ROCKETCHAT_AUTH_TOKEN) and using only:

{
  "mcpServers": {
    "rocketchat": {
      "command": "python",
      "args": ["C:/path/to/rocketchat.py"]
    }
  }
}

---

Docker: no credentials in the container

The image is built and run without any RocketChat credentials. Start with:

docker compose up -d

The server listens on http://0.0.0.0:3011/mcp. Clients (e.g. Nanobot) must send credentials on each request via the headers listed in the credentials table. Optionally you can set ROCKETCHAT_* env vars in the container if you want a default for clients that don’t send headers.

---

Local Python setup (no Docker)

uv venv
.venv\Scripts\activate   # or: source .venv/bin/activate
uv sync

• Stdio (for Nanobot/Cursor): set ROCKETCHAT_* env vars, then run:

  python rocketchat.py
  

  (Nanobot/Cursor will start this for you when configured as above.)

• HTTP (local test):

  set MCP_TRANSPORT=streamable-http
  python rocketchat.py
  

  Or:

  python rocketchat.py --transport streamable-http --port 3011
  

---

Tools exposed to the agent

• list_users – list users
• find_channel – find room(s) by name (channels, DMs, private); returns room_id for messages/send
• list_all_rooms – list all rooms (channels, DMs, private, etc.)
• send_message_in_channel – send a message (channel name or room_id)
• get_channel_messages – get recent messages in a room (requires room_id)
• get_user_info – info for a user
• create_channel – create a channel

To get the last message in channel XY: call find_channel("XY") first, then get_channel_messages(room_id=<from find_channel>, count=1).

---

For more details, see Rocket.Chat API and Nanobot README.