Skip to main content
Glama

Linux Bash MCP Server

by gunjanjp
GitHub
JavaScript
MIT License
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Linux Bash MCP Server

Version License Node.js

A powerful Model Context Protocol (MCP) server that enables Claude Desktop to execute bash commands and scripts in any WSL2 Linux distribution on Windows. Features universal Linux compatibility, intelligent distribution detection, and comprehensive safety measures.

🚀 Quick Start

# 1. Clone the repository git clone https://github.com/yourusername/linux-bash-mcp-server.git cd linux-bash-mcp-server # 2. Run automated setup npm run fix # 3. Restart Claude Desktop # 4. Start using Linux commands in Claude!

✨ Features

  • 🐧 Universal Linux Support - Works with Ubuntu, Debian, Fedora, openSUSE, Alpine, and more

  • 🔍 Smart Distribution Detection - Automatically detects and configures available WSL distributions

  • 🛡️ Safe Configuration Merging - Preserves existing MCP servers when setting up

  • 🔧 Comprehensive Diagnostics - Built-in troubleshooting and auto-fix tools

  • ⚡ High Performance - Optimized command execution with configurable timeouts

  • 📊 Detailed Logging - Debug mode for troubleshooting and monitoring

  • 🔄 Easy Management - Simple scripts for setup, testing, and maintenance

🛠️ Available Tools

Tool

Description

Example Use

execute_bash_command

Run single bash commands

ps aux | grep nginx

execute_bash_script

Execute bash scripts with args

Run monitoring scripts

create_bash_script

Create new bash scripts

Generate automation scripts

list_directory

List directory contents

Browse file systems

get_system_info

Comprehensive system info

Check OS, memory, disk usage

check_wsl_status

WSL and distribution status

Verify connectivity

📋 Prerequisites

  • Windows with WSL2 installed

  • Any Linux distribution in WSL2 (Ubuntu, Debian, etc.)

  • Node.js 18+

  • Claude Desktop App

🎯 Installation & Setup

Option 1: Automated Setup (Recommended)

git clone https://github.com/yourusername/linux-bash-mcp-server.git cd linux-bash-mcp-server npm run fix

Option 2: Manual Setup

# Install dependencies npm install # Run interactive setup npm run setup # Test functionality npm test

Option 3: Quick Diagnostics

# Check for issues npm run debug # Verify configuration npm run check-config

⚙️ Configuration

The server automatically detects your WSL distributions and configures itself. Manual configuration is available in config.json:

{ "wslDistribution": "auto-detect", "defaultTimeout": 30000, "scriptTimeout": 60000, "maxBufferSize": 10485760, "debugMode": false }

🔧 Available Scripts

Command

Description

npm run fix

Auto-fix common issues and setup

npm run setup

Interactive configuration wizard

npm run debug

Comprehensive diagnostics

npm run test

Test all functionality

npm run check-config

Verify configurations

npm start

Start the MCP server

🐧 Supported Linux Distributions

  • Ubuntu (most common)

  • Debian

  • Fedora

  • openSUSE

  • Alpine Linux

  • Kali Linux

  • Oracle Linux

  • And many more...

💡 Usage Examples

Once configured, use these commands in Claude Desktop:

System Administration

  • "Show comprehensive system information for my Linux environment"

  • "Check disk usage and available space"

  • "List running processes sorted by CPU usage"

File Operations

  • "List all files in /var/log with detailed information"

  • "Find files modified in the last 24 hours"

  • "Show directory sizes in /home"

Development Tasks

  • "Check if Docker is running"

  • "Show git status for repositories in my home directory"

  • "List installed Python packages"

Automation

  • "Create a backup script for my documents"

  • "Generate a system monitoring script"

  • "Create a log rotation script"

🛡️ Safety Features

  • Configuration Preservation - Never overwrites existing MCP servers

  • Automatic Backups - Creates backups of corrupted configurations

  • Input Validation - Validates all commands and parameters

  • Timeout Protection - Prevents hanging commands

  • Error Handling - Comprehensive error reporting and recovery

🔍 Troubleshooting

Quick Fixes

npm run fix # Auto-resolve common issues npm run debug # Detailed diagnostics

Common Issues

WSL Not Found

wsl --install wsl --install -d Ubuntu

Dependencies Missing

npm install

Configuration Issues

npm run check-config npm run setup

Server Not Starting

npm run debug

See TROUBLESHOOTING.md for detailed solutions.

🤝 Integration with Other MCP Servers

This server works seamlessly alongside:

  • PowerShell MCP Server (Windows commands)

  • Memory MCP Server (Persistent notes)

  • File MCP Server (File operations)

  • Git MCP Server (Version control)

  • Any other MCP servers

📚 Project Structure

linux-bash-mcp-server/ ├── src/ │ └── index.js # Main MCP server ├── test/ │ └── test.js # Comprehensive tests ├── examples/ │ ├── system_info.sh # Example monitoring script │ └── file_operations.sh # Example file operations ├── config.json # Server configuration ├── setup.js # Interactive setup ├── debug.js # Diagnostic tool ├── quick-fix.js # Auto-fix utility ├── check-config.js # Configuration checker └── README.md # This file

🔄 Version History

v1.0.0 (Current)

  • ✅ Universal Linux distribution support

  • ✅ Intelligent WSL distribution detection

  • ✅ Safe configuration merging

  • ✅ Comprehensive diagnostic tools

  • ✅ Auto-fix utilities

  • ✅ Enhanced error handling

  • ✅ Debug mode support

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Update documentation

  6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

🙏 Acknowledgments

  • Anthropic for the Model Context Protocol

  • Microsoft for WSL2 technology

  • The open-source community for Linux distributions and tools

Made with ❤️ for the Claude Desktop and Linux community

⭐ Star this repository if you find it useful!

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

A Model Context Protocol server that enables Claude Desktop to execute bash commands and scripts in WSL2 Linux distributions on Windows.

  1. 🚀 Quick Start
    1. ✨ Features
      1. 🛠️ Available Tools
        1. 📋 Prerequisites
          1. 🎯 Installation & Setup
            1. Option 1: Automated Setup (Recommended)
            2. Option 2: Manual Setup
            3. Option 3: Quick Diagnostics
          2. ⚙️ Configuration
            1. 🔧 Available Scripts
              1. 🐧 Supported Linux Distributions
                1. 💡 Usage Examples
                  1. System Administration
                  2. File Operations
                  3. Development Tasks
                  4. Automation
                2. 🛡️ Safety Features
                  1. 🔍 Troubleshooting
                    1. Quick Fixes
                    2. Common Issues
                  2. 🤝 Integration with Other MCP Servers
                    1. 📚 Project Structure
                      1. 🔄 Version History
                        1. v1.0.0 (Current)
                      2. 🤝 Contributing
                        1. 📄 License
                          1. 🆘 Support
                            1. 🙏 Acknowledgments

                              Related MCP Servers

                              • Claude TypeScript MCP Servers

                                ukkz
                                A
                                security
                                A
                                license
                                A
                                quality
                                A collection of Model Context Protocol servers that enable Claude Desktop to provide development assistance capabilities with filesystem, Git, shell command, and web search functionality without incurring API usage costs.
                                Last updated -
                                2
                                19
                                MIT License
                                • Apple

                              • MCP Tools

                                ZbigniewTomanek
                                -
                                security
                                A
                                license
                                -
                                quality
                                A custom Model Context Protocol server that gives Claude Desktop and other LLMs access to file system operations and command execution capabilities through standardized tool interfaces.
                                Last updated -
                                24
                                Apache 2.0
                                • Apple
                                • Linux

                              • MCP TaskManager

                                Rudra-ravi
                                A
                                security
                                A
                                license
                                A
                                quality
                                A Model Context Protocol server that allows Claude Desktop to manage and execute tasks in a queue-based system, supporting planning, execution, and completion phases.
                                Last updated -
                                10
                                329
                                6
                                MIT License
                                • Apple

                              • Desktop Commander MCP

                                MrGNSS
                                A
                                security
                                A
                                license
                                A
                                quality
                                A server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.
                                Last updated -
                                19
                                25,181
                                4
                                MIT License
                                • Linux
                                • Apple

                              View all related MCP servers

                              Appeared in Searches

                              New MCP Servers

                              MCP directory API

                              We provide all the information about MCP servers via our MCP API.

                              curl -X GET 'https://glama.ai/api/mcp/v1/servers/gunjanjp/linuxshell-mcp'

                              If you have feedback or need assistance with the MCP directory API, please join our Discord server