R as a server: Configure R-based tools with LLM-enabled apps

mcp_server() implements a model context protocol server with arbitrary R functions as its tools. Optionally, calling mcp_session() in an interactive R session allows those tools to execute inside of that session.

Usage

mcp_server(tools = NULL, ..., session_tools = TRUE)

mcp_session()

Arguments

tools

Optional collection of tools to expose. Supply either a list of objects created by ellmer::tool() or a path to an .R file that, when sourced, yields such a list. Defaults to NULL, which serves only the built-in session tools when session_tools is TRUE.

...

Reserved for future use; currently ignored.

session_tools

Logical value whether to include the built-in session tools (list_r_sessions, select_r_session) that work with mcp_session(). Defaults to TRUE.

Value

mcp_server() and mcp_session() are both called primarily for their side-effects.

• mcp_server() blocks the R process it's called in indefinitely and isn't intended for interactive use.

• mcp_session() makes the interactive R session it's called in available to MCP servers. It returns invisibly the nanonext socket used for communicating with the server. Call close() on the socket to stop the session.

Configuration

mcp_server() should be configured with the MCP clients via the Rscript command. For example, to use with Claude Desktop, paste the following in your Claude Desktop configuration (on macOS, at file.edit("~/Library/Application Support/Claude/claude_desktop_config.json")):

{
  "mcpServers": {
    "r-mcptools": {
      "command": "Rscript",
      "args": ["-e", "mcptools::mcp_server()"]
    }
  }
}

Or, to use with Claude Code, you might type in a terminal:

claude mcp add -s "user" r-mcptools Rscript -e "mcptools::mcp_server()"

mcp_server() is not intended for interactive use.

The server interfaces with the MCP client. If you'd like tools to have access to variables inside of an interactive R session, call mcp_session() to make your R session available to the server. Place a call to mcptools::mcp_session() in your .Rprofile, perhaps with usethis::edit_r_profile(), to make every interactive R session you start available to the server.

On Windows, you may need to configure the full path to the Rscript executable. Examples for Claude Code on WSL and Claude Desktop on Windows are shown at https://github.com/posit-dev/mcptools/issues/41#issuecomment-3036617046.

See also

• The "R as an MCP server" vignette at vignette("server", package = "mcptools") delves into further detail on setup and customization.

• These functions implement R as an MCP server. To use R as an MCP client, i.e. to configure tools from third-party MCP servers with ellmer chats, see mcp_tools().

Examples

# should only be run non-interactively, and will block the current R process
# once called.
if (identical(Sys.getenv("MCPTOOLS_CAN_BLOCK_PROCESS"), "true")) {
# to start a server with a tool to draw numbers from a random normal:
library(ellmer)

tool_rnorm <- tool(
  rnorm,
  "Draw numbers from a random normal distribution",
  n = type_integer("The number of observations. Must be a positive integer."),
  mean = type_number("The mean value of the distribution."),
  sd = type_number("The standard deviation of the distribution. Must be a non-negative number.")
)

mcp_server(tools = list(tool_rnorm))

# can also supply a file path as `tools`
readLines(system.file("example-ellmer-tools.R", package = "mcptools"))

mcp_server(tools = system.file("example-ellmer-tools.R", package = "mcptools"))
}

if (interactive()) {
  mcp_session()
}