Python R-Server MCP

A secure, Docker-based Model Context Protocol (MCP) server for R data visualization and analysis, built with Python and FastMCP.

What is this? This tool allows you to perform statistical analysis in R through natural language conversations with LLM models like Claude. All R code is executed in secure Docker containers, ensuring complete isolation and security.

Key Benefits:

• 🗣️ Natural Language Interface: Chat with AI to perform complex statistical analyses
• 🐳 Secure Docker Execution: All R code runs in isolated containers with network disabled
• 📊 Automatic R Execution: AI runs R code and returns results without you writing code
• 📁 Multiple Directory Mounting: Mount multiple local directories for R to access
• 📈 Inline Plot Capture: Plots automatically returned as base64 PNG images
• 🔒 PII Protection: Optional auto-redaction of personal data before it reaches the LLM
• 💾 Session Persistence: R variables persist between calls
• ⚡ Smart Caching: Configurable result caching for instant repeated operations
• 📦 Auto Library Detection: Missing R packages automatically installed

🌐 Türkçe | English

Overview

This project is inspired by gdbelvin's rlang-mcp-server but is a complete Python reimplementation using the FastMCP framework. While the original Go version provided basic R visualization tools, this Python version extends the functionality with comprehensive security, file management, and data privacy features.

Features

🎨 Visualization & Analysis

• ggplot2 Rendering: Execute R code with ggplot2 commands and return publication-ready visualizations
• Inline Plot Capture: Plots automatically detected and returned as base64 PNG
• R Script Execution: Run any R script with smart file handling and return formatted output
• Session Persistence: R variables and workspace persist between calls via .RData

📁 File Management

• Multiple Directory Mounting: Mount multiple local directories with custom mount points
• Smart File Discovery: Use R scripts to explore and analyze files in mounted directories
• Unmount Support: Cleanly unmount directories when done

📦 Package Management

• Auto Library Detection: library() and require() calls parsed, missing packages auto-installed
• Package Installation: Install R packages on-demand with version control
• Automatic Dependencies: Smart package dependency resolution
• Temporary Network: Network temporarily enabled only during package installation

🛡️ Security & Isolation

• Mandatory Docker: All R code execution in isolated containers
• Network Disabled by Default: Container cannot access internet during R execution
• Resource Limits: Configurable memory (default 2GB) and CPU limits
• PII Redaction: Optional automatic detection and masking of personal data in R output
• Temporary Network Only: Network enabled only for package installs, then disabled
• Container Isolation: Complete process and filesystem isolation
• Enhanced Error Messages: R errors include traceback and call context

🔒 PII Protection (Optional)

• Regex Detection: TC Kimlik No, phone numbers, email, IBAN, credit cards, patient IDs
• NER Name Detection: Person names detected via multilingual spaCy model
• Medical Whitelist: Statistical and medical terms excluded from false positives
• Fallback Support: Works with or without Presidio installed (regex fallback)
• Zero Data Leakage: PII redacted before output reaches the LLM API

🚀 Performance & Experience

• FastMCP Framework: Modern Python MCP implementation (v3.1.1+)
• Smart Caching: Configurable in-memory caching (size + TTL via environment variables)
• Persistent Containers: Reuses same container for all operations (no startup overhead)
• Container Warm-up: Common R packages pre-loaded at container start
• Pre-compiled Packages: Uses Docker images with pre-installed R packages

Quick Start

Prerequisites

• Docker (mandatory - must be running)
• Python 3.12+
• uv (recommended) or pip

macOS

brew install uv
brew install python@3.12
brew install --cask docker

Windows

pip install uv
# Install Python 3.12+ from https://www.python.org/downloads/windows/
# Install Docker Desktop from https://www.docker.com/products/docker-desktop

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3.12 python3.12-venv python3-pip docker.io
pip install uv
sudo systemctl start docker && sudo systemctl enable docker

Note: Local R installation is not required - all R execution happens inside Docker containers.

Installation

# Method 1: Install directly from GitHub (recommended)
uvx --from git+https://github.com/saidsurucu/rlang-mcp-python rlang-mcp-python

# Method 2: Clone and install locally
git clone https://github.com/saidsurucu/rlang-mcp-python.git
cd rlang-mcp-python
uv sync

# Method 3: Install with pip
pip install git+https://github.com/saidsurucu/rlang-mcp-python

# Optional: Install PII protection
pip install 'rlang-mcp-server[privacy]'
uv pip install https://github.com/explosion/spacy-models/releases/download/xx_ent_wiki_sm-3.8.0/xx_ent_wiki_sm-3.8.0-py3-none-any.whl

Claude Desktop Integration

1. Open Claude Desktop
2. Go to Settings > Developer > Edit Config
3. Add this configuration:

{
  "mcpServers": {
    "r-server-python": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/saidsurucu/rlang-mcp-python",
        "rlang-mcp-python"
      ]
    }
  }
}

With Environment Variables (Recommended for Sensitive Data)

{
  "mcpServers": {
    "r-server-python": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/saidsurucu/rlang-mcp-python",
        "rlang-mcp-python"
      ],
      "env": {
        "R_MCP_PII_ENABLED": "true",
        "R_MCP_NETWORK_DISABLED": "true",
        "R_MCP_MEM_LIMIT": "4g"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
R_MCP_MEM_LIMIT	2g	Container memory limit
R_MCP_CPU_QUOTA	200000	CPU quota (100000 = 1 CPU)
R_MCP_CACHE_TTL	3600	Cache time-to-live in seconds
R_MCP_CACHE_SIZE	100	Maximum cached results
R_MCP_SESSION	true	Persist R variables between calls
R_MCP_NETWORK_DISABLED	true	Container network isolation
R_MCP_PII_ENABLED	false	PII redaction on R output

Tools Available

This server provides 7 tools:

Tool	Description	Category
mount_directory	Mount local directories (supports multiple, custom mount points)	Directory
unmount_directory	Unmount directories (single or all)	Directory
execute_r_script	Run R code with plot capture, auto library detection, session persistence, PII redaction	Execution
container_status	Check health, resources, R version, session, cache stats	Monitoring
initialize_r_container	Start container with resource limits and warm-up	Container
install_r_package	Install packages on-demand (temp network enable)	Packages
clear_session	Clear R workspace (remove persisted variables)	Session

PII Protection

When working with sensitive data (healthcare, financial, personal), enable PII protection to automatically redact personally identifiable information from R output before it reaches the LLM.

How It Works

R code runs in Docker (local, network disabled)
    ↓
R output (stdout)
    ↓ R_MCP_PII_ENABLED=true
[Presidio Regex] → TC, phone, email, IBAN, credit card, patient ID
[spaCy NER]      → Person names (Ali Yılmaz, Mehmet Öz...)
[Whitelist]      → Filter false positives (medical/statistical terms)
    ↓
Sanitized output → LLM API (no PII leaves your machine)

What Gets Redacted

PII Type	Example	Redacted As
TC Kimlik No	12345678901	<TR_TC_KIMLIK>
Phone	0532 456 7890	<TR_PHONE>
Email	ali@mail.com	<EMAIL>
IBAN	TR33000610...	<TR_IBAN>
Credit Card	4532-1234-5678-9012	<CREDIT_CARD>
Patient ID	Hasta No: 2024-15832	<TR_HASTA_NO>
Person Name	Ali Yılmaz	<PERSON>

What Passes Through (No False Positives)

• mean=45.2, sd=12.3, n=150 — aggregate statistics
• table(data$diagnosis) — frequency tables
• HbA1c, Tip 2 Diyabet — medical terms
• Min. 1st Qu. Median Mean — R output

Fallback Behavior

Installed	Detection
presidio + xx_ent_wiki_sm	Full: regex + name detection
presidio only	Regex: TC, phone, email, IBAN, credit card
Neither	Pure regex fallback (no extra dependencies)

Security Model

┌─────────────────────────────────────────────────┐
│                 Security Layers                  │
├─────────────────────────────────────────────────┤
│ 1. Docker Isolation    │ All R code in container │
│ 2. Network Disabled    │ No internet by default  │
│ 3. Resource Limits     │ Memory + CPU caps       │
│ 4. PII Redaction       │ Output sanitized        │
│ 5. Temp Network Only   │ Package installs only   │
└─────────────────────────────────────────────────┘

Usage Examples

Basic Analysis

"Mount my data directory at /Users/me/data and analyze the sales_data.xlsx file. Show summary statistics and monthly trends."

Visualization

"Create a publication-ready boxplot comparing revenue by quarter using my data."

Sensitive Data (with PII enabled)

"Load the patient data and show me aggregate statistics: mean age, diagnosis distribution, and HbA1c levels by treatment group."

R output is automatically sanitized — even if raw data is accidentally printed, personal information is redacted before reaching the AI.

Session Workflow

# Step 1: Load data (persists in session)
execute_r_script("data <- read_excel('/data/patients.xlsx')")

# Step 2: Analyze (data variable still available)
execute_r_script("summary(data)")

# Step 3: Visualize (still in session)
execute_r_script("ggplot(data, aes(x=age)) + geom_histogram()")

# Step 4: Clean up
clear_session()

Docker Support

Docker is mandatory for security. The server uses pre-built Docker images:

1. semoss/docker-r-packages (primary — comprehensive R packages)
2. rocker/tidyverse (fallback — data science packages)
3. r-base (final fallback — minimal R)

Images are automatically pulled on first use. The container:

• Runs with network disabled (re-enabled only for package installs)
• Has memory and CPU limits enforced
• Persists across all operations in the session
• Is automatically cleaned up on server shutdown

Development

# Install development dependencies
uv sync --dev

# Install PII protection for testing
uv pip install presidio-analyzer presidio-anonymizer spacy
uv pip install https://github.com/explosion/spacy-models/releases/download/xx_ent_wiki_sm-3.8.0/xx_ent_wiki_sm-3.8.0-py3-none-any.whl

# Run linting
uv run ruff check
uv run black --check .

Troubleshooting

Docker Issues

# Ensure Docker is running
docker --version

# Start Docker (Linux)
sudo systemctl start docker

# macOS/Windows: Ensure Docker Desktop is running

PII Protection Issues

# Check if presidio is installed
python -c "import presidio_analyzer; print('OK')"

# Install NER model for name detection
uv pip install https://github.com/explosion/spacy-models/releases/download/xx_ent_wiki_sm-3.8.0/xx_ent_wiki_sm-3.8.0-py3-none-any.whl

# Verify NER model works
python -c "import spacy; nlp = spacy.load('xx_ent_wiki_sm'); print('NER OK')"

Common Issues

• First run slow: Normal — Docker image pull + container setup (~15-30s)
• Package install fails: Network temporarily enabled, check Docker network
• Container unresponsive: Restart the MCP server
• PII not detected: Ensure R_MCP_PII_ENABLED=true is set

Comparison with Original

Feature	Original (Go)	This Version (Python)
Core Tools	2	7
Directory Mounting	❌	✅ (multiple)
Plot Capture	Basic	✅ (auto base64 PNG)
Session Persistence	❌	✅ (.RData)
Auto Library Install	❌	✅
Network Isolation	❌	✅ (default)
PII Protection	❌	✅ (Presidio + NER)
Resource Limits	❌	✅ (memory + CPU)
Container Healthcheck	❌	✅
Modern Framework	❌	✅ (FastMCP 3.1+)

Contributing

Contributions are welcome! Please submit pull requests for any enhancements.

License

Creative Commons Attribution-NonCommercial 4.0 International (CC-BY-NC 4.0)

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

Acknowledgments

• Inspired by gdbelvin's rlang-mcp-server
• Built with FastMCP
• PII protection powered by Microsoft Presidio and spaCy
• Powered by uv for fast Python package management