ClaudeR

Connect RStudio directly to Claude Desktop, Claude Code, Codex, Gemini CLI, or any other MCP based AI assistant for interactive coding and data analysis.

ClaudeR is an R package that forges a direct link between RStudio and MCP configured AI assistants like Claude Code or Codex. This enables interactive coding sessions where the AI can execute code in your active RStudio environment and see the results in real-time. Whether you need an autonomous data explorer or a coding collaborator, ClaudeR adapts to your workflow.

This package is also compatible with Cursor and any service that support MCP servers.

# Install
if (!require("devtools")) install.packages("devtools")
devtools::install_github("IMNMV/ClaudeR")

# Set up your AI tool
library(ClaudeR)
install_clauder()          # For Claude Desktop / Cursor
install_cli(tools = "claude")  # For Claude Code CLI

# Start the server in RStudio
claudeAddin()

AI agents: See llms-install.md for automated setup instructions.

Check out this YouTube video for a quick demonstration of what to expect when you use ClaudeR:

• Quick Start
• Features
• How It Works
• CLI Integration
• Security Restrictions
• Installation
• Usage
• Logging Options
• Example Interactions
• Important Notes
• Troubleshooting
• Limitations
• License
• Contributing

ClaudeR empowers your AI assistant with a suite of tools to interact with your R environment:

• execute_r: Execute R code and return the output.
• execute_r_with_plot: Execute R code that generates a plot.
• execute_r_async: Execute long-running R code asynchronously (>25 seconds). Returns a job ID for polling.
• get_async_result: Poll for the result of an async job. Includes a built-in delay to throttle polling.
• list_sessions: List all active RStudio sessions the agent can connect to.
• connect_session: Connect to a specific RStudio session by name for multi-session workflows.
• get_session_history: View execution history filtered by agent ID.
• read_file: Read any text file from disk (.R, .qmd, .csv, .log, etc.) without needing it open in RStudio.
• get_active_document: Get the content of the active document in RStudio.
• get_r_info: Get information about the R environment.
• modify_code_section: Modify a specific section of code in the active document.
• insert_text: Insert text at the current cursor position or a specific line/column in the active document.
• get_viewer_content: Read HTML content from the viewer pane (plotly, DT, leaflet widgets) with pagination support.
• create_task_list: Generate a task list based on your prompt to prevent omissions in long-context tasks.
• update_task_status: Track progress for each task in the generated list.

With these tools, you can:

• Direct Code Execution: The AI can write, execute, and install packages in your active RStudio session.
• Feedback & Assistance: Get explanations of your R scripts or request edits at specific lines.
• Visualization: The AI can generate, view, and refine plots and visualizations.
• Data Analysis: Let the AI analyze your datasets and iteratively provide insights.
• Multi-Agent Workflows: Run Claude Desktop, Claude Code, and Gemini CLI on the same R session simultaneously. Each agent is uniquely identified, and they can see each other's work through shared history and log files.
• Long-Running Analysis: Async execution handles model fitting, simulations, and large data processing without timing out.
• Code Logging: Save all code executed by the AI to log files for future reference. Every entry is tagged with the agent that ran it.
• Console Printing: Print the AI's code to the console before execution.
• Environment Integration: The AI can access variables and functions in your R environment.
• Dynamic Summaries: Summaries can dynamically pull results from objects and data frames to safeguard against hallucinations.
• Quarto Renders: The AI can create and render Quarto presentations. For best results, ask for a .qmd file and for it to be rendered in HTML when it's finished.

ClaudeR uses the Model Context Protocol (MCP) to create a bidirectional connection between an AI assistant and your RStudio environment. MCP is an open protocol from Anthropic that allows the AI to safely interact with local tools and data.

Here's the workflow:

1. The Python MCP server acts as a bridge.
2. The AI sends a code execution request to the MCP server.
3. The server forwards the request to the R add-in running in RStudio.
4. The code executes in your R session, and the results are sent back to the AI.

This architecture ensures that the AI can only perform approved operations through well-defined interfaces, keeping you in complete control of your R environment.

ClaudeR now supports command-line interface (CLI) tools like the Claude Code CLI, the OpenAI Codex CLI, and the Google Gemini CLI. This is ideal for developers who prefer a terminal-based workflow, allowing you to interact with your AI assistant directly from the command line while maintaining a live connection to your RStudio session.

For your safety, ClaudeR implements strict restrictions on code execution:

• System Commands: All system(), system2(), shell(), and other methods of executing system commands are blocked.
• File Deletion: Operations that could delete files (like unlink(), file.remove(), or system commands containing rm) are prohibited.
• Error Messages: When the AI attempts to run restricted code, the operation is blocked, and a specific error message is returned explaining why.

1. Data Protection: Prevents accidental deletion or modification of important files.
2. Controlled Environment: Ensures the AI remains a safe tool for collaboration.
3. Principle of Least Privilege: Grants only the necessary permissions for data analysis tasks.
4. Predictable Behavior: Creates clear boundaries for automated actions.

These restrictions only apply to code executed by the AI. Your manually executed R code is not affected.

Run this command in your RStudio console:

if (!require("devtools")) install.packages("devtools")
devtools::install_github("IMNMV/ClaudeR")

Choose the option that matches your workflow.

This function configures the MCP config file automatically for desktop applications. By default it uses uvx to run the clauder-mcp PyPI package, which handles all Python dependencies automatically.

# Load the package
library(ClaudeR)

# Run the installer for Claude Desktop
install_clauder()

# Optional: For Cursor users
# install_clauder(for_cursor = TRUE)

For users who cannot use uvx (e.g. restricted environments), fall back to the legacy Python path method:

library(ClaudeR)
install_clauder(use_uvx = FALSE, python_path = "/path/to/your/python")

This non-interactive function generates the exact command or JSON configuration needed for your CLI tool.

library(ClaudeR)

# For Claude Code CLI
install_cli(tools = "claude")

# For OpenAI Codex CLI
install_cli(tools = "codex")

# For Google Gemini CLI
install_cli(tools = "gemini")

For users who cannot use uvx, fall back to the legacy Python path method:

install_cli(tools = "claude", use_uvx = FALSE, python_path = "/path/to/my/python")

After running the function, you must manually apply the configuration:

• For Claude / Codex: Copy the command printed in the R console and run it in your terminal.
• For Gemini: Copy the generated JSON and manually add it to your gemini.json settings file.

After setup, quit and restart any active Desktop Apps or terminal sessions for the new settings to load.

Note: If you upgrade R versions, re-run install_cli() or install_clauder() to update the MCP server path. The CLI installer automatically removes stale registrations before adding fresh ones.

For all workflows, you must first start the ClaudeR server from RStudio.

library(ClaudeR)
claudeAddin()

The ClaudeR add-in will appear in your RStudio Viewer pane. Click "Start Server". Keep this window active while using your preferred tool.

• For Desktop Apps: Open the Claude Desktop App or Cursor and begin your session.
• For CLI Tools: Open your terminal and use the claude or gemini commands to start interacting with your AI assistant.

Note: You can regain console/active document control by clicking the stop button in the RStudio console. This closes the Shiny UI but the MCP server keeps running in the background — your AI agents stay connected. Re-run claudeAddin() to bring the viewer pane back with the same server state (port, session name, execution count). To fully stop the server, click "Stop Server" in the UI before closing.

• Print Code to Console: See the AI's code in your R console before it runs. The code will be preceded by the header: ### LLM [agent-id] executing the following code ###.
• Log Code to File: Save all executed code to a log file. Each entry is tagged with the agent ID that executed it, so you can trace which AI agent ran what.
• Custom Log Path: Specify a custom location for log files.
• Descriptive Filenames: Log files are named clauder_<session>_<port>_<timestamp>.R (e.g., clauder_default_8787_20260301_143022.R) so you can tell at a glance which session produced which log.
• Reproducibility Header: Each log starts with a header containing the date, working directory, and full sessionInfo() output (R version, platform, attached/loaded packages). This makes logs self-documenting for reproducibility.
• Export Clean Script: Click "Export Clean Script" in the logging panel to produce a runnable .R file stripped of all timestamps and log headers. Error blocks are kept as comments so you can see what went wrong. Also callable from the console with export_log_as_script().

A new log file is created each time you click Start Server. All code executed by agents appends to that file until you stop and start the server again.

• "I have a dataset named data in my environment. Perform exploratory data analysis on it."
• "Load the mtcars dataset and create a scatterplot of mpg vs. hp with a trend line."
• "Fit a linear model to predict mpg based on wt and hp."
• "Generate a correlation matrix for the iris dataset and visualize it."
• "I have a qmd file active. Please make a nice quarto presentation on gradient descent. The audience is very technical. Make sure it looks smooth. Save the presentation in /Users/nyk/QuartoDocs/"

If you can do it with R, your AI assistant can too.

• Session Persistence: Variables, data, and functions created by the AI remain in your R session.
• Code Visibility: By default, the AI's code is printed to your console.
• Port Configuration: The default port is 8787, but you can change it if needed.
• Package Installation: The AI can install packages. Use clear prompts to guide its behavior.

• Connection Issues:
  • Ensure your AI tool is configured correctly.
  • Verify the Python path in your config or CLI command.
  • Make sure the server is running in the add-in.
  • Restart RStudio if the port is in use.
• Python Dependency Issues:
  • could not find function install_clauder: Restart your R session (Session -> Restart R) and try again.
  • MCP Server Failed to Start: If using uvx, ensure uv is installed (curl -LsSf https://astral.sh/uv/install.sh | sh). If using the legacy method, this usually means the wrong Python environment was detected. Re-run the installer with the correct python_path or switch to use_uvx = TRUE.
• AI Can't See Results:
  • Ensure the add-in window is open and the server is running.
• Plots Not Displaying:
  • Instruct the AI to wrap plot objects in print() (e.g., print(my_plot)).
  • Tell the AI to use the execute_r_with_plot function.
• Long-Running Code Timing Out:
  • Ask the AI to use execute_r_async for code that takes longer than 25 seconds.
  • The AI will automatically poll for results using get_async_result.
  • Async jobs run in a separate R process via callr and do not have access to your main session's environment. The AI must write self-contained code that uses saveRDS() to pass data in and write results out, then loads them back into the main session after the job completes.
• Server Restart Issues:
  • If you see an "address already in use" error after restarting the server, it's a UI bug. The server is still active. If you encounter connection issues, switch the port number in the Viewer Pane or restart RStudio.
  • If the AI still can't connect, save your work and click "Force Kill Server" in the viewer pane. This will terminate the active RStudio window.
• Stale MCP Path After R Upgrade:
  • If tools stop working after upgrading R, re-run install_cli() or install_clauder() to update the script path.

• Each R session can connect to one Claude Desktop/Cursor app at a time. However, multiple CLI agents (Claude Code, Gemini CLI) can share the same session alongside a Desktop app. To isolate agents, run separate RStudio windows with different session names and ports.
• You can stop the connection to the Shiny UI by clicking the Stop button in the console to make changes alongside the AI, but to stop the connection you will need to restart the RSession.
• R is single-threaded, but async jobs run in a separate process via callr so the main session stays responsive. The background process does not share the main session's environment, so async code must be self-contained.

This project is licensed under the MIT License. See the LICENSE file for details.

Contributions are welcome! Please feel free to submit a Pull Request.