# MCP Rocket.Chat Setup Guide

Rocket.Chat MCP server for [Nanobot](https://github.com/HKUDS/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):

   ```bash
   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):

   ```json
   {
     "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):
   ```json
   "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:

   ```bash
   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`):

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

   Or with `uv` from the project directory:

   ```json
   {
     "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):

```json
{
  "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:

```json
{
  "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:

```bash
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)

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

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

  ```bash
  python rocketchat.py
  ```

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

- **HTTP (local test):**

  ```bash
  set MCP_TRANSPORT=streamable-http
  python rocketchat.py
  ```

  Or:

  ```bash
  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](https://docs.rocket.chat/) and [Nanobot README](https://github.com/HKUDS/nanobot/blob/main/README.md).