MCP Linux Shell Server

A secure Model Context Protocol (MCP) server that provides Linux shell command execution capabilities for Claude Desktop on Linux

Features

• Safe Shell Execution: Execute Linux commands with proper error handling
• Directory Management: Change and query current working directory
• MCP Protocol Compliant: Full compatibility with the Model Context Protocol
• Async Architecture: Built with modern async/await patterns
• Comprehensive Testing: Well-tested with 89% code coverage

Prerequisites

• Python 3.8 or higher
• Debian GNU/Linux 12 (bookworm) x86_64 or Later
• Claude Desktop (for integration) There is no official Claude Desktop app for Linux; the following repository works but is no longer maintained by the creator. claude-desktop-debian

Installation

1. Clone the Repository

git clone https://github.com/Frost26/mcp-linux-shell-server.git
cd mcp-linux-shell-server

2. Create Virtual Environment

python3 -m venv mcpEnv
source mcpEnv/bin/activate

3. Install Dependencies

# Install core dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install -r requirements-dev.txt

4. Verify Installation

# Run tests to ensure everything works
python -m pytest tests/ -v --cov=linux_shell_server

Claude Desktop Configuration

1. Locate Your Claude Desktop Config

The configuration file is typically located at:

~/.config/claude/claude_desktop_config.json

2. Add MCP Server Configuration

Add the following to your Claude Desktop config file:

{
  "mcpServers": {
    "linux-shell": {
      "command": "/path/to/your/mcp-linux-shell-server/mcpEnv/bin/python",
      "args": [
        "-m",
        "linux_shell_server.main"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/mcp-linux-shell-server"
      }
    }
  }
}

3. Update Paths

Replace /path/to/your/mcp-linux-shell-server with your actual project directory path.

Example for this project:

{
  "mcpServers": {
    "linux-shell": {
      "command": "/home/AI/Documents/CodeProjects/mcp-linux-shell-server/mcpEnv/bin/python",
      "args": [
        "-m",
        "linux_shell_server.main"
      ],
      "env": {
        "PYTHONPATH": "/home/AI/Documents/CodeProjects/mcp-linux-shell-server"
      }
    }
  }
}

4. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

Available Tools

The MCP server provides three main tools:

Development

Running Tests

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=linux_shell_server --cov-report=html

# Run specific test file
python -m pytest tests/test_main.py -v

Code Formatting

# Format code with Black
black linux_shell_server/ tests/

# Check code style with Ruff
ruff check linux_shell_server/ tests/

# Sort imports with isort
isort linux_shell_server/ tests/

Type Checking

mypy linux_shell_server/

Security Considerations

• Commands are executed in the context of the user running the MCP server
• No built-in command filtering or sandboxing (use with caution)
• Error outputs are captured and returned safely
• Working directory changes are isolated to the server process

Troubleshooting

Common Issues

1. Claude Desktop can't connect to MCP server

• Verify the paths in your Claude Desktop config are correct
• Check that the virtual environment is properly activated
• Ensure all dependencies are installed

2. Permission errors when executing commands

• The MCP server runs with the same permissions as the user
• Ensure the user has appropriate permissions for the commands being executed

3. Module not found errors

• Verify PYTHONPATH is set correctly in the Claude Desktop config
• Ensure the virtual environment contains all required dependencies

Debug Mode

To run the server in debug mode for troubleshooting:

# Activate virtual environment
source yourEnv/bin/activate

# Run server directly
python -m linux_shell_server.main

Resources

• Model Context Protocol Documentation
• MCP Python SDK
• Claude Desktop MCP Guide

License

This project is licensed under the MIT License