Chelu97/claude-local-control

Claude Local Control

MCP Server for direct control of your real local PC via Claude Code

Control your real computer - mouse, keyboard, screenshots, bash, file editing - all through Claude Code using the Model Context Protocol (MCP).

🎯 What is this?

This is an MCP server that allows Claude Code to control your real local PC directly:

• 🖱️ Mouse and keyboard control
• 📸 Automatic screenshots with every action
• 🐚 Persistent bash shell sessions
• 📝 Real filesystem file editing
• 🖥️ Everything happens on your real screen

vs Docker Version

This project is adapted from claude-desktop-control, but instead of running in an isolated Docker container, it controls your real local machine.

🚀 Quick Start

Prerequisites

• Ubuntu/Debian Linux with X11/Xwayland
• Node.js and npm
• Python 3.10+
• Claude Code CLI

Installation

# 1. Clone the repository
cd ~/Personal
git clone https://github.com/YOUR_USERNAME/claude-local-control.git
cd claude-local-control

# 2. Run the installer (installs dependencies, creates venv, compiles MCP)
./install.sh

# 3. Add MCP to Claude Code
claude mcp add local-control -- bash ~/Personal/claude-local-control/start-mcp.sh

# 4. Verify installation
claude mcp list
# Should show: local-control: ... - ✓ Connected

# 5. IMPORTANT: Restart Claude Code if it was already running
# (for the MCP to be fully activated)

Usage

In Claude Code, activate Local Control Mode:

/local

[Your task here]

The /local command automatically loads the appropriate context for controlling your real PC.

🛠️ Available Tools

1. computer - PC Control

Control your real computer with mouse, keyboard, and screenshots:

• screenshot: Capture your real screen
• mouse_move: Move mouse to coordinates [x, y]
• left_click, right_click, middle_click: Mouse clicks
• double_click, triple_click: Multiple clicks
• left_click_drag: Drag from current position to [x, y]
• key: Press key/combo (e.g., "Return", "ctrl+c")
• type: Type text
• scroll: Scroll in direction with amount
• cursor_position: Get current cursor position
• wait: Wait N seconds and take screenshot

✨ Key Feature: Every action automatically returns a screenshot showing the result.

2. bash - Persistent Shell

Persistent bash session on your real system:

• Working directory persists between commands
• Environment variables maintained
• Runs as your actual user
• Full access to your filesystem

3. str_replace_editor - File Editor

Edit files on your real filesystem:

• view: View file or list directory
• create: Create new file
• str_replace: Replace text in file
• insert: Insert text at line number
• undo_edit: Undo last edit

⚠️ Warning: Changes are permanent on your real system.

🧠 When to Use What

Use computer (MCP tools) when:

• ✅ You need to interact with GUI applications
• ✅ Booking hotels, making reservations, online purchases
• ✅ Visual validation is required
• ✅ Using desktop apps (Firefox, LibreOffice, calculator, etc.)
• ✅ Complex navigation that blocks bots
• ✅ Anything requiring "see and click"

Use Claude Code native tools when:

• ✅ Web scraping / data extraction (WebFetch, WebSearch)
• ✅ Code generation, CSV creation, data processing
• ✅ Quick information searches
• ✅ File manipulation on host
• ✅ Reading/analyzing files (Read, Grep, Glob)

Use HYBRID strategy when:

1. Generate content with native tools (fast)
2. Transfer via workspace ~/claude-local-workspace/
3. Format/present with computer in desktop apps

⚡ Efficiency Strategies

Scripts > Clicks

❌ BAD: Create 1000 rows in Excel by clicking one by one (10 hours)

✅ GOOD:

# Generate CSV with Python (30 seconds)
bash({ command: `python3 << 'EOF'
import csv
data = [['Product', 'Price', 'Stock']]
for i in range(1000):
    data.append([f'Item {i}', 100 + i, 50 + i])
with open('$HOME/claude-local-workspace/data.csv', 'w') as f:
    csv.writer(f).writerows(data)
EOF` })

# Import in LibreOffice (2 minutes)
computer({ action: 'screenshot' })
# Open Calc, File > Open, select CSV

Workspace for File Transfer

Use ~/claude-local-workspace/ to transfer files between native tools and desktop apps.

📁 Project Structure

claude-local-control/
├── tools/                    # Python MCP tools
│   ├── computer.py          # Screen control (adapted for local)
│   ├── bash.py              # Persistent shell
│   └── edit.py              # File editor
├── mcp-server/              # Node.js MCP server
│   ├── src/
│   │   ├── index.ts         # MCP server entry point
│   │   ├── bridge.ts        # Python-Node.js bridge (adapted)
│   │   └── tools/           # Tool definitions
│   └── package.json
├── .claude/
│   └── commands/
│       └── local.md         # /local slash command
├── install.sh               # Installation script
├── start-mcp.sh            # MCP launcher (created by install.sh)
├── CLAUDE.md               # Complete usage guide
├── EXAMPLES.md             # Practical examples
└── README.md               # This file

🔒 Security Considerations

⚠️ IMPORTANT WARNING:

This MCP has FULL ACCESS to your real PC:

• Can execute any command as your user
• Can read/modify any file you have access to
• Can control mouse/keyboard on your real screen
• Can see everything you see

Only use this with tasks you trust Claude to perform.

Unlike the Docker version, there's no isolation or sandboxing. Every action happens directly on your real system.

📊 System Information

• Display: Auto-detected from $DISPLAY environment (typically :0)
• Resolution: Auto-detected via xrandr (fallback: 1920x1080)
• Workspace: ~/claude-local-workspace/ (for file transfers)
• Screenshots: /tmp/claude-local-outputs/
• Python venv: ~/.claude-local-venv/
• User: Your real system user

📚 Documentation

• : Complete guide to using the system
• : Detailed examples with correct/incorrect strategies
• : /local command documentation

🎓 Philosophy

"Optimize for speed with smart strategies, but ALWAYS complete 100% of the requested work. Claude Sonnet 4.5 can work up to 7 hours non-stop - there's no excuse for leaving work incomplete."

Key principles:

• 🧠 ULTRATHINK before acting - choose the optimal strategy
• 📸 Always start with a screenshot to see current state
• ⚡ Optimize but always complete the full task
• 🎯 100% completion - never abandon partial work
• 🔒 Be careful - this is your real PC

🛠️ Development

Building the MCP Server

cd mcp-server
npm install
npm run build

Testing

After installation, you can test each tool:

# In a new Claude Code session
/local

# Test 1: Screenshot
computer({ action: "screenshot" })

# Test 2: Mouse movement
computer({ action: "mouse_move", coordinate: [960, 540] })

# Test 3: Bash
bash({ command: "pwd && whoami" })

# Test 4: File editor
str_replace_editor({ command: "view", path: "/home/chelu/.bashrc" })

🤝 Contributing

This is a personal adaptation of the Anthropic computer-use demo. Feel free to fork and adapt for your own needs.

📄 License

Based on Anthropic's computer-use demo. Adapted for local system control.

⚠️ Disclaimer

This tool provides Claude Code with direct control over your real computer. Use it responsibly and only for tasks you trust. The authors are not responsible for any unintended actions or system modifications.

Ready to control your PC with Claude Code?

/local

What should I do on your computer?