stat-guy/bash

Advanced MCP Bash Server

The most advanced bash execution server for AI assistants, providing superior capabilities beyond Claude's built-in bash tool.

🚀 Why Choose This Server?

Superior to Claude's Native Bash Tool

• ✅ Multi-session management: Run isolated bash environments simultaneously
• ✅ Enhanced session analytics: Track creation time, usage, command count, and background jobs
• ✅ Advanced process control: Configurable timeouts, background execution, custom working directories
• ✅ Production-ready reliability: Comprehensive error handling and session lifecycle management

Perfect For

• Claude Code: Enhanced bash capabilities for development workflows
• Cursor Agent CLI: Superior command execution with session isolation
• Custom AI assistants: Full MCP protocol support with advanced features

Key Advantages

• 95% API compatibility with Claude's bash tool + superior features
• Zero session contamination between different tasks
• Advanced background job handling with proper process management
• Full bash scripting support including heredocs, loops, and complex operations
• Configurable execution parameters for maximum control

⚡ Quick Setup

For Experts (30 seconds)

git clone https://github.com/stat-guy/bash.git
cd bash
npm install
pip3 install mcp pydantic

Configure in Claude Desktop (~/.config/claude_desktop_config.json):

{
  "mcpServers": {
    "bash": {
      "command": "node",
      "args": ["path/to/bash/mcp-bash-wrapper.js"]
    }
  }
}

For Claude Code Users (10 seconds)

git clone https://github.com/stat-guy/bash.git
cd bash && npm install && pip3 install mcp pydantic
claude mcp add bash node /ABSOLUTE/PATH/TO/bash/mcp-bash-wrapper.js

Replace /ABSOLUTE/PATH/TO/ with your actual folder path!

For Beginners (Step-by-step)

1. Prerequisites

• Python 3.10+: Download from python.org
• Node.js 14+: Download from nodejs.org
• Git: Download from git-scm.com

2. Download & Install

# Clone the repository
git clone https://github.com/stat-guy/bash.git
cd bash

# Install Node.js dependencies  
npm install

# Install Python dependencies
pip3 install mcp pydantic

3. Test Installation

# Test the server starts correctly
npm test

You should see: MCP server ready

4. Configure Claude Desktop

macOS: Edit ~/.config/claude_desktop_config.json Windows: Edit %APPDATA%\claude_desktop_config.json

{
  "mcpServers": {
    "bash": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/bash/mcp-bash-wrapper.js"]
    }
  }
}

⚠️ Important: Use the absolute path to mcp-bash-wrapper.js

5. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the new server.

🔧 Session Configuration

The server automatically manages sessions with these defaults:

• Session timeout: 1 hour of inactivity
• Cleanup interval: Every 5 minutes
• Command timeout: 30 seconds (configurable per command)
• Working directory: User's current directory (configurable per session)

📖 Usage Examples

Basic Commands

# Execute simple commands
execute_command("ls -la")
execute_command("pwd")

# Chain commands with persistence
execute_command("cd /tmp && export VAR=value")
execute_command("echo $VAR")  # Outputs: value

Multi-Session Management

# Create isolated sessions
create_session("project-a", "/path/to/project-a")
create_session("project-b", "/path/to/project-b") 

# Execute in specific sessions
execute_command("npm install", session_id="project-a")
execute_command("pip install -r requirements.txt", session_id="project-b")

Background Execution

# Long-running commands in background
execute_command("npm run build", background=True, timeout=300)
execute_command("docker build .", background=True)

🛠 Available Tools

🔍 Troubleshooting

Common Issues

Server not starting:

# Check dependencies
python3 -c "import mcp, pydantic"
node --version

Claude not finding server:

• Verify absolute paths in configuration
• Restart Claude Desktop completely
• Check Claude Desktop logs for error messages

Permission errors:

# Ensure execute permissions
chmod +x mcp-bash-wrapper.js

Python path issues:

# Verify Python can find the module
cd /path/to/bash
python3 -c "import sys; sys.path.insert(0, 'src'); from mcp_bash_server import server"

Getting Help

• Issues: GitHub Issues
• Documentation: See agents.md and claude.md for AI-specific instructions
• Example Config: Check claude_desktop_config.example.json

📊 Performance & Reliability

• Execution time: 0.02-0.05s for basic commands
• Large output handling: Tested with 1000+ line outputs
• Session isolation: 100% guaranteed separation
• Error handling: Comprehensive timeout and failure recovery
• Memory management: Automatic cleanup of stale sessions

🔒 Security Features

• Process isolation: Each session runs in separate process groups
• Resource limits: Configurable timeouts and size limits
• Clean termination: Proper signal handling and cleanup
• Environment control: Isolated environment variables per session

📄 License

MIT License - see file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Ready to supercharge your AI assistant's bash capabilities?

⭐ Star this repo and experience the difference!