mcp-terminal

The MCP Terminal server provides a secure, controlled interface to execute shell commands and manage npm operations within a Model Context Protocol setup. It restricts commands to a curated list, supports timeouts, and lets you manage environment variables and working directories. Typical actions include running arbitrary commands within a safe scope, installing npm packages, and executing npm scripts. The server exposes methods such as executeCommand, install, and runScript, and convenience commands like dev and build map to npm scripts. This enables you to automate and constrain terminal workflows from within your MCP-enabled environment.

To use it, connect through an MCP client that can invoke the terminal interface. You can execute commands with custom working directories, install dependencies, and run npm scripts. For example, you can run a directory-wide listing, install TypeScript, or run a build script, all under the server’s configured security and timeout controls. The example usage shows executing a command, performing npm installations, and invoking npm script helpers like dev and build.

Prerequisites:

• Node.js and npm installed on the host where MCP is running
• Access to run shell commands allowed by the server configuration

Step-by-step:

1. Install the MCP Terminal server package: npm install @modelcontextprotocol/server-terminal

2. Ensure your MCP config includes the terminal server block (see the repository README for details). Example: { "terminal": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-terminal"], "autoApproveScope": ["execute_command", "npm_install", "npm_run"], "config": { "allowedCommands": ["npm", "node", "git"], "defaultTimeout": 30000, "defaultCwd": "/your/project/path", "environmentVariables": { "NODE_ENV": "development" } } } }

3. Start or deploy the MCP stack as you normally would (e.g., via your MCP server harness, docker, or your chosen runtime).

4. Verify the terminal endpoint is reachable through your MCP client and that allowed commands, environment, and working directory behave as configured.

Tips and notes:

• The server enforces a whitelist of allowedCommands (e.g., npm, node, git). Update this list to fit your project needs.
• DefaultTimeout is in milliseconds; adjust to balance responsiveness and long-running tasks.
• defaultCwd sets the working directory for commands; ensure the path exists and is accessible by the runtime environment.
• Environment variables defined in config are applied to executed commands. Use them to configure NODE_ENV, API keys, etc.
• If commands fail due to permissions, verify the host user has execute rights in the configured directory and that the allowedCommands list covers the intended tools.
• For TypeScript projects or TS toolchains, you can rely on npm install and npm scripts to bootstrap and compile.
• When using npx with server-terminal, the package will be installed (or used from cache) for each run as configured by the mcp config.