What is Mcp Linux Shell Server

The mcp-linux-shell-server is a secure Model Context Protocol (MCP) server that enables the execution of Linux shell commands specifically for the Claude Desktop environment on Linux systems.

Use cases

Use cases include executing shell commands remotely, managing directories in a secure manner, integrating with applications that require command execution, and facilitating development workflows in Linux-based environments.

How to use

To use the mcp-linux-shell-server, clone the repository, create a virtual environment, install the necessary dependencies, and configure it within the Claude Desktop settings. Ensure that your Claude Desktop configuration file includes the MCP server settings.

Key features

Key features include safe shell execution with error handling, directory management capabilities, full compliance with the MCP protocol, an asynchronous architecture using modern async/await patterns, and comprehensive testing with 89% code coverage.

Where to use

The mcp-linux-shell-server is suitable for developers and users who require secure command execution in Linux environments, particularly those using Claude Desktop for development or automation tasks.

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