Linux MCP Server

AI-driven Linux desktop control via Model Context Protocol.

Overview

Linux MCP Server exposes Linux desktop operations (file management, app control, clipboard, notifications) as MCP tools. AI assistants can use these tools to perform actions on behalf of the user.

Architecture

AI Assistant (Claude, Ollama, etc.)
    │
    │ MCP (HTTP+SSE)
    ▼
Linux MCP Server (Python)
    │
    ├── Safety Layer (Safe/Elevated/Blocked permissions)
    │
    └── Tools: file_read, app_launch, clipboard, notifications

Security Model

Level	Description	Example
SAFE	No confirmation needed	Read files, launch apps, clipboard
ELEVATED	Requires user confirmation	Write files, run shell commands
BLOCKED	Never allowed	sudo, kernel access

All AI-initiated actions are logged to an audit trail.

Quick Start

Installation

pip install linux-mcp

Run

# Set compositor auth key (optional but recommended)
export LINUX_MCP_COMPOSITOR_KEY="your-secret-key"

# Start the MCP server
linux-mcp

Connect to Claude Desktop

Add to ~/.claude-desktop-config.json:

{
  "mcpServers": {
    "linux-desktop": {
      "command": "uvx",
      "args": ["linux-mcp"],
      "env": {
        "LINUX_MCP_COMPOSITOR_KEY": "your-secret-key"
      }
    }
  }
}

Available Tools

File Operations

• file_read - Read file contents
• file_list - List directory
• file_write (ELEVATED) - Write files

App Control

• app_launch - Launch applications

System

• clipboard_read - Read clipboard
• notification_send - Send notifications
• settings_get / settings_set - System settings

Development

# Clone and install
git clone https://github.com/YOUR_USER/linux-mcp.git
cd linux-mcp
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run in dev mode
python -m linux_mcp

License

MIT