terminal-mcp-server

Secure Terminal-Only MCP Server

This project provides a secure Model-Context-Protocol (MCP) server that allows terminal command execution in a controlled environment. It's designed to be used with AI assistants and other clients that need terminal access while keeping confidential information protected.

Features

• Path Restrictions: Only allows command execution in pre-configured directories
• Command Filtering: Optional allowlist/blocklist for commands
• Output Sanitization: Automatically redacts sensitive information
• Resource Limits: Configurable timeouts and output size limits
• Docker Ready: Run in an isolated container for enhanced security

Installation

# Install globally
npm install -g terminal-mcp-server

# Or install locally in your project
npm install terminal-mcp-server

Quick Start

# Initialize configuration (creates terminal-tool.json and terminal-security.json)
terminal-mcp-server --init

# Edit the configuration files to specify allowed paths and security settings

# Start the server
terminal-mcp-server

Security Configuration

The server includes two levels of security configuration:

1. Basic Path Restriction (terminal-tool.json):

   {
     "allowedPaths": [
       "/public/data",
       "/public/scripts"
     ]
   }

2. Enhanced Security (terminal-security.json):

   {
     "allowedPaths": [
       "/public/data",
       "/public/scripts"
     ],
     "commandSecurity": {
       "enabled": true,
       "allowedCommands": ["ls", "cat", "grep", "find"],
       "blockedCommands": ["curl", "wget", "ssh"],
       "timeoutSeconds": 5
     },
     "outputFiltering": {
       "enabled": true
     }
   }

Docker Usage

# Pull the image
docker pull your-org/terminal-only-mcp-server:latest

# Run with default settings
docker run -d \
  -e PUBLIC_DIR_1=/public/data \
  -e PUBLIC_DIR_2=/public/scripts \
  -v /path/on/host/data:/public/data \
  -v /path/on/host/scripts:/public/scripts \
  your-org/terminal-only-mcp-server:latest

Connecting Clients

Any MCP-compatible client can connect to this server. Example with the official SDK:

import { Client } from '@modelcontextprotocol/sdk/client';
import { createCliTransport } from '@modelcontextprotocol/sdk/client/cli';

async function connectToTerminalServer() {
  const transport = createCliTransport('/path/to/terminal-only-mcp-server');
  const client = new Client();
  await client.connect(transport);
  
  // List available tools
  const tools = await client.listTools();
  console.log(tools);
  
  // Execute a terminal command
  const result = await client.callTool('terminal', {
    command: 'ls -la',
    workingDir: '/public/data'
  });
  
  console.log(result.content[0].text);
}

Security Best Practices

1. Isolated Environments: Run the server in a container or virtual machine
2. Least Privilege: Allow only necessary paths and commands
3. Regular Updates: Keep the server and dependencies updated
4. Audit Logs: Monitor the logs for suspicious activity
5. Content Review: Validate all files in shared directories

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.