agentR

English | 中文

MCP server for interactive R sessions. Let AI agents execute R code in a persistent R session — local or remote via SSH.

Two modes:

• Spawn mode (default): AI starts a new R process and controls it exclusively
• Attach mode: AI connects to an existing R session (e.g., your RStudio Server session) for human-AI collaboration with shared variables

Recommended Agent: CodeWhale

CodeWhale is a Rust-based coding agent with first-class MCP support. It's the recommended client for agentR.

Install agentR

git clone https://github.com/yuumeHuang/agentR.git
cd agentR
npm install
npm run build

Configure in CodeWhale

Option A: In TUI (quick)

Launch CodeWhale TUI, then run:

/mcp add stdio agentR node --arg "/absolute/path/to/agentR/dist/index.js"

Set environment variables with:

/mcp env agentR AGENT_R_SSH_HOST your-server.com
/mcp env agentR AGENT_R_SSH_USER username
/mcp env agentR AGENT_R_SSH_PASSWORD password

Option B: Edit config file

Edit ~/.deepseek/mcp.json:

Spawn mode (AI creates a new remote R session via SSH):

{
  "servers": {
    "agentR": {
      "command": "node",
      "args": ["/absolute/path/to/agentR/dist/index.js"],
      "env": {
        "AGENT_R_SSH_HOST": "your-server.com",
        "AGENT_R_SSH_USER": "username",
        "AGENT_R_SSH_PASSWORD": "password"
      }
    }
  }
}

Attach mode (AI joins your existing RStudio Server session):

{
  "servers": {
    "agentR": {
      "command": "node",
      "args": ["/absolute/path/to/agentR/dist/index.js"],
      "env": {
        "AGENT_R_MODE": "attach",
        "AGENT_R_SSH_HOST": "your-server.com",
        "AGENT_R_SSH_USER": "username",
        "AGENT_R_SSH_PASSWORD": "password",
        "AGENT_R_ATTACH_PORT": "9876"
      }
    }
  }
}

Verify in CodeWhale

/mcp list            # Should show agentR as enabled
/mcp tools agentR    # Should list 6 tools: r_execute, r_inspect, r_plot, etc.

Attach Mode — Human + AI Collaboration

Attach mode lets you and the AI agent share the same R session. Variables, data frames, and plots are shared in real-time.

Step 1: Install R packages on the server

install.packages(c("httpuv", "jsonlite"))

Step 2: Upload agentR.R to the server

Copy R/agentR.R to your server (e.g., via SCP or RStudio file upload).

Step 3: Start the server in RStudio Console

source("agentR.R")
agentR_serve(9876)

RStudio console remains fully interactive — you can keep typing commands.

Step 4: Configure CodeWhale with attach mode

Use the attach mode config above with AGENT_R_MODE=attach and AGENT_R_ATTACH_PORT=9876.

Stop the server

agentR_stop()

Tools

Tool	Description
r_execute	Execute R code in the persistent session
r_inspect	Inspect R objects (str, class, dim, summary, head, glimpse)
r_plot	Generate plots and return as PNG images
r_install_packages	Install R packages
r_session_info	Get R version, loaded packages, working directory
r_reset	Reset the R session (kill + restart)

Environment Variables

Variable	Default	Description
AGENT_R_MODE	spawn	spawn = new R process, attach = join existing session
AGENT_R_PATH	R	Path to R binary
AGENT_R_TIMEOUT	60000	Idle timeout in ms — resets on each output chunk (sliding window)
AGENT_R_MAX_TOTAL_TIMEOUT	600000	Absolute max execution time in ms regardless of output
AGENT_R_SSH_HOST	—	SSH host (enables SSH mode)
AGENT_R_SSH_PORT	22	SSH port
AGENT_R_SSH_USER	—	SSH username
AGENT_R_SSH_PASSWORD	—	SSH password
AGENT_R_SSH_KEY	—	SSH private key (file path or content)
AGENT_R_SSH_PASSPHRASE	—	Passphrase for private key
AGENT_R_ATTACH_PORT	9876	Port for attach mode (httpuv server)

Architecture

Spawn Mode                          Attach Mode
┌────────────────┐                 ┌─────────────────────┐
│  AI Agent      │                 │  Human (RStudio)    │
│  (MCP client)  │                 │  ┌───────────────┐  │
└───────┬────────┘                 │  │ R console     │  │
        │                          │  │ httpuv :9876  │  │
        ▼                          │  └───────┬───────┘  │
┌────────────────┐                 └──────────┼──────────┘
│  agentR MCP    │  SSH tunnel                │
│  server        │◄───────────────────────────┤
│  (Node.js)     │                            │
└───────┬────────┘                            │
        │ SSH exec ("R")        SSH forwardOut │
        ▼                                     ▼
┌────────────────┐                 ┌────────────────────┐
│  New R process │                 │  Existing R session│
│  (exclusive)   │                 │  (shared)          │
└────────────────┘                 └────────────────────┘

Requirements

• Node.js >= 18
• R >= 4.0 (on local or remote machine)
• For attach mode: httpuv and jsonlite R packages
• For SSH: remote server accessible via password or key auth

License

MIT