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

``bash


Install globally

npm install -g terminal-mcp-server

Or install locally in your project

npm install terminal-mcp-server
`

Quick Start

`bash


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):
`json
{
"allowedPaths": [
"/public/data",
"/public/scripts"
]
}
`

2. Enhanced Security (terminal-security.json):
`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

`bash


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:

`javascript
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.