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:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Update documentation
Submit a pull request

📄 License

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

🆘 Support

Issues: GitHub Issues
Documentation: Project Wiki
Discussions: GitHub Discussions

🙏 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!