R mcp setup

R MCP Setup

Two supported paths for connecting Claude Code to R as native MCP tools instead of one-shot Bash Rscript -e calls:

• mcp-repl — Claude owns a long-lived R subprocess; state persists across tool calls. Headless, no IDE required.
• btw + mcptools — Claude connects to your running R session in RStudio / Positron; inspects the same objects you can see.

All MCP features are optional — every skill works fully without them. Both paths can be registered at the same time; tool names don't collide.

Lazy references:

• Read references/mcp-repl-setup.md for the full mcp-repl walkthrough (install options, sandbox modes, session control, comparison table)
• Read references/mcp-tool-mappings.md for the tool → skill mapping and Bash fallback commands
• Read references/mcp-troubleshooting.md for common setup issues
• Read references/ide-awareness-helpers.md for cc_plot(), cc_env(), and cc_view() (closes the Positron Assistant visual-awareness gap)

---

Two Paths — Which One?

Path	Process owner	Best for	Survives IDE restart	Sandbox
mcp-repl	Claude Code	Headless agent work, autonomous analysis	N/A (no IDE)	Built-in, on by default
btw + mcptools	You (RStudio/Positron)	Pairing inside an IDE; inspecting your env pane objects	Requires re-running btw_mcp_session()	None

Lead with mcp-repl when the work is "let Claude run R for me." Reach for btw + mcptools when you want Claude to see what you are doing in your own console.

---

Path A — mcp-repl (default for agent work)

Quick-start (full detail in references/mcp-repl-setup.md):

1. Install the binary. Easiest route is PyPI — the distribution is named posit-mcp-repl and installs an mcp-repl executable:

   uv tool install posit-mcp-repl
   

   pipx install posit-mcp-repl, the official install script, cargo install, and prebuilt release tarballs all work too — see the reference. Neither PyPI wheels nor prebuilt binaries bundle R; R must already be installed and discoverable.

2. Verify: mcp-repl --help should resolve.

3. Wire it into Claude Code using mcp-repl's own installer rather than claude mcp add:

   mcp-repl install --client claude --interpreter r
   

   This writes ~/.claude.json (plus a permission entry in ~/.claude/settings.json) with the correct flag values already filled in: --sandbox workspace-write --oversized-output files --interpreter r. Omit --interpreter r to register Python as well.

   The server is registered under the name r, so the tool arrives as mcp__r__repl. This is the name Posit's own docs and the tidyverse AGENTS.md files assume — prefer it over a custom name.

4. Verify connection: claude mcp list shows r as connected.

5. Use it. One tool becomes available:

   • repl — execute R in a persistent subprocess. Params are input (the code, as a string) and optional timeout_ms (milliseconds). Variables, packages, and fitted models persist across calls.

   There is no separate reset tool. The portable way to reset is an in-band quit() — it ends the worker, the next call starts a fresh one, and it travels as ordinary text through any client. Control-byte prefixes on input are the alternative: \u0004 (Ctrl-D / EOF) resets, \u0003 (Ctrl-C / SIGINT) interrupts a running call. Those require the client to deliver a genuine raw control byte, which not every JSON encoding path does — reach for quit() first.

Sandbox note: mcp-repl is sandboxed by default — workspace-write with network access disabled. Omitting --sandbox does not disable it. Install R packages from your own R session; the agent consumes what's already in the library it can see. To let the agent hit the network (e.g. install.packages()), it must be registered with --sandbox danger-full-access. --sandbox inherit-codex is Codex-only and fails closed under Claude Code.

Large outputs: --oversized-output takes a value. files (what the installer writes) keeps the reply short and saves the full transcript as a bundle the agent can open on demand; pager (the bare default) instead gives in-band paging.

---

Path B — btw + mcptools (IDE integration)

For users working in RStudio or Positron who want Claude to see live session state, plots, and tabular previews from the same console they're typing in.

What mcptools and btw Provide

Package	Purpose
mcptools	Makes R act as an MCP server; bridges Claude Code into your live R console
btw	Wraps mcptools and supplies the R-aware tool groups

btw 1.3.0 ships thirteen tool groups. Register a subset — the ones below are the useful set for Claude Code, which already has its own file, git, and web tools:

Group	What Claude Code Gets
docs	Help pages, vignettes, NEWS for installed packages
pkg	Structured test/check/document/coverage results
env	Inspect data frames and environments in a live R session
run	Execute R code in the user's session
cran	CRAN package discovery and metadata
sessioninfo	Installed package checks, platform info

Deliberately excluded because Claude Code duplicates them natively: files, git, github, ide, web, agent, skills.

Note: search and cran are the same group, as are session and sessioninfo. The short forms still resolve — verified on btw 1.3.0, they yield a byte-identical 18-tool set — but they are deprecated and now emit a lifecycle warning (btw_tools('search') was deprecated in btw 1.2.0). An existing registration keeps working; migrate it anyway to keep the server's stderr clean. Use the canonical cran / sessioninfo spellings; the tool names they produce are btw_tool_cran_* and btw_tool_sessioninfo_*.

Setup steps

Use TaskCreate when running the full setup — one task per step. Mark each in_progress when starting, completed when its gate passes.

B.1 — Detect current state. Run the shared detection script:

bash "${CLAUDE_PLUGIN_ROOT}/hooks/detect-mcp.sh"

Returns JSON with btw_installed, mcptools_installed, mcp_registered, mcp_repl_installed, mcp_repl_registered, and tool_groups (the group list this skill recommends, not a probe of what is actually registered).

Alternatively check manually:

requireNamespace("btw", quietly = TRUE)
requireNamespace("mcptools", quietly = TRUE)

claude mcp list

B.2 — Install packages. If either is missing:

install.packages(c("mcptools", "btw"))

For renv projects:

renv::install("mcptools")
renv::install("btw")
renv::snapshot()

B.3 — Register the MCP server (project-scoped):

claude mcp add -s "project" r-btw -- Rscript -e "btw::btw_mcp_server(tools = btw::btw_tools(c('docs', 'pkg', 'env', 'run', 'cran', 'sessioninfo')))"

Yields 18 tools. Server starts automatically when Claude Code opens this project.

Windows: may need the full path to Rscript.exe — see references/mcp-troubleshooting.md.

B.4 — Connect your live R session. In Positron / RStudio:

btw::btw_mcp_session()

Without this, env and run tools see only the MCP server's own R process, not your workspace. (mcptools::mcp_session() is the underlying function and works identically; btw_mcp_session() is the documented btw-native entry point.)

Add to ~/.Rprofile for auto-start:

if (interactive()) {
  if (!nzchar(Sys.getenv("MCP_REPL_INTERPRETER"))) {
    try(btw::btw_mcp_session(), silent = TRUE)
  }
  try(
    local({
      helpers <- new.env()
      source("~/.claude/scripts/cc-helpers.R", local = helpers)
      attach(helpers, name = "cc-helpers", warn.conflicts = FALSE)
    }),
    silent = TRUE
  )
}

Two things in that snippet are not decoration:

• The MCP_REPL_INTERPRETER guard is required if you also run mcp-repl. Its worker sources ~/.Rprofile and reports interactive() == TRUE, and the sandbox permits local Unix sockets — so a bare if (interactive()) bridges Claude's own headless sandboxed worker as a live session, where btw_tool_run_r can silently land instead of your IDE. See "Using Both Paths Together" below.
• attach() rather than source() keeps the helpers out of the global environment that cc_env() reports on.

.Rprofile shadowing — check this first. R sources exactly one .Rprofile, and a project-local one wins outright; ~/.Rprofile is then never read and this whole block is inert. If the project has its own profile, put if (file.exists("~/.Rprofile")) source("~/.Rprofile") at the top of it — before renv/activate.R in renv projects. See references/mcp-troubleshooting.md B9.

B.5 — Verify. claude mcp list should show r-btw as connected.

B.6 — (Optional) close the IDE-awareness gap. cc_plot(), cc_env(), and cc_view() write artifacts to .claude/scratch/ so Claude can read your plots, workspace summary, and tabular previews. Install:

1. Copy ${CLAUDE_PLUGIN_ROOT}/skills/r-mcp-setup/scripts/cc-helpers.R to ~/.claude/scripts/cc-helpers.R (once, for all projects; a project-local .claude/scripts/ copy also works)
2. Attach from ~/.Rprofile (see B.4)
3. Add .claude/scratch/ to .gitignore, and ^\.claude$ to .Rbuildignore for packages — not ^\.claude/scratch/$, which matches nothing

Detail in references/ide-awareness-helpers.md.

---

Using Both Paths Together

mcp-repl and btw + mcptools can be registered simultaneously. Tool names don't collide: mcp-repl exposes repl (as mcp__r__repl under the default server name); btw exposes btw_tool_*. Common pattern: use repl for agent-owned stateful execution, and btw_tool_env_describe_data_frame to introspect data frames that you yourself loaded in your IDE.

Guard the bridge when both are active. The mcp-repl worker sources ~/.Rprofile, reports interactive() == TRUE, and can open the local Unix socket the bridge uses — so an unguarded if (interactive()) btw::btw_mcp_session() registers that sandboxed headless worker as a live session alongside your IDE. btw_tool_run_r may then execute in the worker instead of your console, with no error to signal it. Claude reaches the worker directly via mcp__r__repl anyway, so the correct posture is to never bridge it:

if (!nzchar(Sys.getenv("MCP_REPL_INTERPRETER"))) {
  try(btw::btw_mcp_session(), silent = TRUE)
}

If a stray session has already registered, list_r_sessions and select_r_session (mcptools ≥ 1.0.0) let you pick the right one; older mcptools has no selector and simply keeps whichever registered first.

---

How Skills Use MCP Tools

There is no magic context string to look for. Decide by checking your own available tools:

`repl` present            → agent-owned persistent execution
`btw_tool_run_r` present  → single-call execution in the user's IDE session
neither                   → fall back to Bash `Rscript -e` (parse text output)

The session-start hook independently prints a one-line tip naming whichever paths it detected, so the user knows what they have. That tip is advisory; the tool list is the source of truth. See references/mcp-tool-mappings.md for the full mapping.

---

Removing MCP Registration

claude mcp remove r               # drops the mcp-repl registration
claude mcp remove r-btw           # drops the btw/mcptools registration

Substitute the actual server name if you registered under a different one. Both leave the underlying binaries / packages installed.

---

Examples

• "Set up mcp-repl for persistent R sessions in Claude Code"
• "How do I install the Posit mcp-repl binary"
• "Connect Claude Code to my live R session in Positron"
• "Which btw tools should I register for package development?"
• "My MCP server isn't connecting — help me troubleshoot"
• "What's the difference between mcp-repl, mcptools, and btw?"