MCP Terminal Server

The MCP Terminal Server provides a secure command-line interface through the Model Context Protocol (MCP), enabling AI models to interact with your terminal while enforcing strict permissions and safe file access. It focuses on executing commands and managing environment variables within allowed paths, giving you controlled, remote-terminal capabilities across platforms.

How to use

You enable the MCP Terminal Server as an MCP endpoint and connect an MCP client to it to run terminal commands, work with files, and manage environment variables from your AI models. The server restricts actions to the paths you specify and sanitizes commands to prevent unsafe operations. Once connected, you can execute commands, access authorized directories, and pass environment data to commands securely.

How to install

Prerequisites you need before installing:
- Node.js and npm or a compatible Node runtime
- A supported MCP client that can load an MCP server configuration
- A directory you want to allow for file operations (paths should be clearly defined)

# Clone the MCP Terminal Server project
git clone https://github.com/dillip285/mcp-terminal.git

# Move into the project directory
cd mcp-terminal

# Install dependencies
npm install

# Configure npm authentication if you plan to publish or fetch private packages
cp .npmrc.example .npmrc
# Edit .npmrc and add your NPM_TOKEN

# Run tests to verify everything works
npm test

# Build the project for distribution
npm run build

Additional notes

Configure the MCP client to use the terminal server by adding a server entry that points to the MCP Terminal package. The server configuration uses an MPC runtime command to load the terminal package and specify the allowed file paths.

Security

Security is enforced through:

• Only allowed paths are accessible for file operations
• Commands are validated and sanitized before execution
• Environment variables are carefully managed
• Proper error handling for security-related issues

Configuration and usage examples

To enable the MCP Terminal Server in your MCP client, configure the server with the following settings. This example uses npx to run the terminal package and restricts access to a specific path.

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": [
        "@dillip285/mcp-terminal",
        "--allowed-paths",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Troubleshooting

If you encounter issues during usage, verify that the client config points to the correct server entry name and that the allowed paths exist and are accessible by the runtime. Check that environment variables are provided if your workflow requires them and review any error messages for hints about permission problems or path restrictions.

Notes

This server supports cross-platform operation (Windows, macOS, Linux) and remote system command execution within the configured constraints.

Available tools

execute_command

Run terminal commands securely (including SSH and remote commands)