btwExtra

Extra MCP tools and helpers built on top of the {btw} package for connecting R sessions with LLMs.

Installation (development)

From GitHub:

remotes::install_github("brianmsm/btwExtra")

Current tool

• btwExtra_tool_env_run_r_code: escape hatch to run arbitrary R code in the connected session. Emulates the R console (prints visible values, skips assignments) and truncates output to 20 lines by default; set max_output_lines = -1 to disable truncation. Prefer the more specific btw_tool_*/btwExtra_tool_* tools when available.

Example usage

Register btw + btwExtra tools with an ellmer chat:

library(ellmer)
ch <- ellmer::chat_anthropic()
ch$register_tools(c(btw::btw_tools(), btwExtra::btwExtra_tools()))

# Ask the model to use the run-R-code tool; output will be truncated by default.
ch$respond("Run 1 + 1 in R and show the result.")

Quick local check of the user-facing tool (outside of chat):

res <- btwExtra::btwExtra_tool_env_run_r_code("library(dplyr); mtcars %>% filter(cyl == 6) %>% summarise(value = mean(hp))")
res

## <btwExtra::BtwExtraToolResult>
##  @ value  : chr "     value\n1 122.2857"
##  @ error  : NULL
##  @ extra  :List of 1
##  .. $ data:List of 5
##  ..  ..$ status          : chr "ok"
##  ..  ..$ console         : chr [1:2] "     value" "1 122.2857"
##  ..  ..$ result_class    : chr NA
##  ..  ..$ n_output_lines  : int 2
##  ..  ..$ max_output_lines: int 20
##  @ request: NULL

Truncation notice: by default, the “long output truncated” guidance is shown once per session. To always show it:

options(btwExtra.show_truncation_notice_once = FALSE)

MCP configuration

Use the combined btw + btwExtra tools:

[mcp_servers.r-btw]
command = "Rscript"
args = [
  "-e",
  "btwExtra::btwExtra_mcp_server()"  # btw::btw_tools() + btwExtra::btwExtra_tools()
]

If needed, you can pass a custom set of tools, e.g. only docs from btw plus everything from btwExtra:

args = [
  "-e",
  "btwExtra::btwExtra_mcp_server(tools = c(btw::btw_tools('docs'), btwExtra::btwExtra_tools()))"
]

Alternatively, you can call btw::btw_mcp_server() directly and pass the combined tools:

args = [
  "-e",
  "btw::btw_mcp_server(tools = c(btw::btw_tools('docs'), btwExtra::btwExtra_tools()))"
]

MCP config for Claude Code or Cursor

Claude CLI:

claude mcp add -s "user" r-btw -- Rscript -e "btwExtra::btwExtra_mcp_server()"

Cursor/VS Code style JSON:

{
  "r-btw": {
    "command": "Rscript",
    "args": ["-e", "btwExtra::btwExtra_mcp_server()"]
  }
}

Very important: register the R session

Any R session you want to use with MCP must call mcptools::mcp_session() so the MCP server can discover and attach to it. The easiest way is to add this call to your .Rprofile (user- or project-level), so it runs automatically when the session starts.

Project-level .Rprofile (placed in the project root), or user-level .Rprofile:

• Windows: C:/Users/<USER>/Documents/.Rprofile
• macOS/Linux: ~/.Rprofile

Example contents:

if (interactive() && requireNamespace("mcptools", quietly = TRUE)) {
  mcptools::mcp_session()
}

This will automatically register any interactive R session with mcptools, making it available to MCP clients (e.g. Codex, ChatGPT, etc.).