A
licenseA
qualityA
maintenanceA secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.
1
191
MIT
MCP Terminal Server
by RinardNick
This server allows you to securely execute terminal commands with controlled access and resource management:
Command Execution: Run shell commands and capture their output (stdout, stderr) along with exit codes
Security Controls: Restrict commands to a predefined list to prevent unauthorized actions and command injection
Resource Management: Set limits on execution time (timeout) and maximum output size to prevent resource exhaustion
Customizable Settings: Configure allowed commands and resource limits on a per-request basis
Communication: Uses the Model Context Protocol (MCP) for interaction
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Terminal Serverlist files in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Terminal Server
A secure terminal execution server implementing the Model Context Protocol (MCP). This server provides controlled command execution capabilities with security features and resource limits.
Features
Command Execution: Execute shell commands with output capture and error handling
Security Controls: Restrict allowed commands and prevent command injection
Resource Controls:
Command timeouts
Maximum output size limits
MCP Protocol Support:
Standard MCP message format
Capability advertisement
Streaming output support
Related MCP server: MCP Terminal
Development
Local Setup
# Clone the repository
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal
# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
# Install development dependencies
uv pip install -e ".[dev]"Publishing to PyPI
# Build the package
uv pip install build
python -m build
# Upload to PyPI
uv pip install twine
python -m twine upload dist/*Testing with MCP Inspector
The MCP Inspector tool can be used to test the server implementation:
# Install inspector
npm install -g @modelcontextprotocol/inspector
# Test server
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"Running Tests
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_terminal.py
# Run with coverage
pytest --cov=mcp_terminal tests/Using with Claude Desktop
Once the package is published to PyPI:
Install UV (if not already installed):
pip install uvInstall the Package using UV:
uv pip install mcp-terminalConfigure Claude Desktop: Edit your Claude Desktop config file (typically at
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS):{ "mcpServers": { "terminal": { "command": "uv", "args": [ "pip", "run", "mcp-terminal", "--allowed-commands", "python,pip,git,ls,cd", "--timeout-ms", "30000", "--max-output-size", "1048576" ] } } }
Protocol Implementation
The server implements the Model Context Protocol (MCP) with the following capabilities:
Capabilities Advertisement
{
"protocol": "1.0.0",
"name": "terminal",
"version": "1.1.0",
"capabilities": {
"execute": {
"description": "Execute a terminal command",
"parameters": {
"command": {
"type": "string",
"description": "The command to execute"
}
},
"returns": {
"type": "object",
"properties": {
"exitCode": { "type": "number" },
"stdout": { "type": "string" },
"stderr": { "type": "string" },
"startTime": { "type": "string" },
"endTime": { "type": "string" }
}
}
}
}
}Message Format
Request:
{
"type": "execute",
"data": {
"command": "echo 'hello world'"
}
}Response:
{
"type": "result",
"data": {
"command": "echo 'hello world'",
"exitCode": 0,
"stdout": "hello world\n",
"stderr": "",
"startTime": "2024-01-20T12:34:56.789Z",
"endTime": "2024-01-20T12:34:56.790Z"
}
}Error:
{
"type": "error",
"data": {
"message": "command not allowed"
}
}Security Considerations
Command Validation:
Only allowed commands can be executed
Shell operators are blocked
Command injection attempts are prevented
Resource Protection:
Command timeouts prevent hanging
Output size limits prevent memory exhaustion
Error handling for all failure cases
Best Practices:
Always set
allowed-commandsin productionUse conservative timeout and size limits
Monitor command execution logs
Contributing
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Available Tools
1 toolrun_commandC
Run a terminal command with security controls.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| allowedCommands | No | Optional list of allowed command executables | |
| command | Yes | The command to execute | |
| maxOutputSize | No | Maximum output size in bytes (default: 1MB) | |
| timeoutMs | No | Maximum execution time in milliseconds (default: 30 seconds) |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions 'security controls' which suggests safety features, it doesn't specify what those controls are, what permissions are required, whether commands run in a sandbox, what happens on failure, or any rate limits. The description provides minimal behavioral context beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single sentence that communicates the core purpose and a key characteristic ('with security controls'). Every word earns its place, and there's no unnecessary verbiage or repetition. It's front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a command execution tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns (success/failure indicators, output format, error handling), doesn't detail the security controls mentioned, and provides minimal behavioral context. Given the potential complexity and risks of command execution, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so all parameters are documented in the structured schema. The description adds no additional parameter information beyond what's already in the schema descriptions. The baseline score of 3 is appropriate when the schema does the heavy lifting for parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Run') and resource ('a terminal command'), specifying it's for executing commands in a terminal environment. It adds the qualifier 'with security controls' which provides important context about the tool's nature. However, without sibling tools, it cannot demonstrate differentiation from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus other approaches or alternatives. It doesn't mention prerequisites, typical use cases, or scenarios where this tool would be preferred over direct terminal access or other execution methods. The 'security controls' mention hints at a context but doesn't provide explicit usage rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
B3.1/5.0
Disambiguation5/5
With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined as running terminal commands with security controls, making it distinct by default.
Naming Consistency5/5
The single tool follows a clear verb_noun pattern (run_command), which is consistent and predictable. Since there are no other tools to compare against, it inherently maintains perfect naming consistency.
Tool Count2/5
A single tool for a terminal server is too few for the apparent scope, as terminal operations typically involve multiple actions (e.g., list files, navigate directories, monitor processes). This minimal set feels thin and incomplete for the domain.
Completeness2/5
The tool surface is severely incomplete for a terminal server domain. While run_command covers command execution, there are obvious gaps such as listing files, checking system status, or managing processes, which will likely cause agent failures in typical terminal workflows.
Maintenance
ActivityInactive
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Run commands and read/write files on your servers over Termalin's keyless tunnels (hosted MCP).
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
An MCP server for Arcjet - the runtime security platform that ships with your AI code.
Related MCP Servers
- AlicenseCqualityCmaintenanceA server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).327MIT
- AlicenseCqualityDmaintenanceA secure server that implements the Model Context Protocol (MCP) to enable controlled execution of authorized shell commands with stdin support.1MIT
- AlicenseBqualityCmaintenanceA secure Model Context Protocol server that allows AI assistants to execute terminal commands with controlled directory access and command permissions. It features a robust security architecture including whitelisting, session IDs, and categorized command levels to ensure safe system interaction.8MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RinardNick/mcp-terminal'
If you have feedback or need assistance with the MCP directory API, please join our Discord server