bash mcp

A TypeScript application that allows Claude to safely execute bash commands with security safeguards.

Features

• Execute bash commands in a controlled environment
• Support for both stateless and stateful (interactive) command execution
• Security safeguards:
• Whitelisted commands
• Whitelisted directories
• Command validation
• Output sanitization
• Session management for interactive commands
• Comprehensive logging

Installation

npm install
npm run build

Configuration

The configuration is stored in config/default.json. You can customize:

• Allowed commands
• Allowed directories
• Session settings
• Security settings
• Logging settings

Example configuration:

{
  "allowedCommands": ["ls", "cat", "echo", "pwd"],
  "allowedDirectories": ["/tmp", "/home"],
  "session": {
    "timeout": 300,
    "maxActiveSessions": 5,
    "defaultMode": "stateless"
  },
  "security": {
    "validateCommandsStrictly": true,
    "sanitizeOutput": true,
    "maxOutputSize": 1048576,
    "commandTimeout": 30
  },
  "logging": {
    "level": "info",
    "file": "logs/bash-mcp.log",
    "maxSize": 10485760,
    "maxFiles": 5
  }
}

Usage

Simple Command Execution

import { executeCommand } from 'bash-mcp';

const result = await executeCommand('ls -la', { cwd: '/home/user' });
console.log(result.output);

Interactive Sessions

import { initBashMCP } from 'bash-mcp';

const mcp = await initBashMCP();

// Create a session
const session = mcp.createSession('/home/user');
const sessionId = session.sessionId;

// Execute a command in the session
const result1 = await mcp.executeCommand('ls -la', { sessionId });
console.log(result1.output);

// Send input to the session
const result2 = await mcp.sendInput({ sessionId, input: 'echo "Hello, world!"' });
console.log(result2.output);

// Close the session when done
mcp.closeSession(sessionId);

Security Considerations

This MCP is designed with security in mind, but it's important to:

• Keep the allowed commands and directories list as restrictive as possible
• Regularly review and update the configuration
• Monitor the logs for suspicious activity
• Keep the MCP and its dependencies up to date

Development

Building

npm run build

Linting and Formatting

To check for linting issues:

npm run lint

To automatically fix linting and formatting issues:

./fix-lint.sh

Or manually:

npm run lint:fix  # Fix linting issues
npm run format    # Format code

Testing

npm test