# 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

```bash
pip install linux-mcp
```

### Run

```bash
# 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`:

```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

```bash
# 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