Skip to main content
Glama
rnd-pro

terminal-x-mcp

by rnd-pro
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Terminal[X]MCP Banner

Multi-Agent Terminal Automation System with Command Planning and Security Validation

License Node.js Version Status

Terminal[X]MCP is a Model Context Provider (MCP) server that enables intelligent terminal automation through a multi-agent system with distributed specialized roles for command execution, security validation, and real-time monitoring.

Automate your terminal workflows intelligently - Works seamlessly with Cursor, Claude Desktop, VS Code, and other MCP-compatible applications while providing secure command execution and comprehensive monitoring.

✨ Features

🤖 Multi-Agent Architecture

  • Terminal Coordinator: Intelligent command planning and workflow orchestration

  • Command Executor: Safe command execution with environment management

  • Security Monitor: Command security analysis and risk prevention

  • Terminal Monitor: Real-time process monitoring and performance tracking

🧠 Auto-Intelligence

  • Command Planning: Automatic command sequence optimization

  • Security Validation: Real-time command risk assessment

  • Workflow Orchestration: Multi-step terminal automation

  • Error Recovery: Intelligent failure handling and retry strategies

🔄 Agent Coordination

  • Distributed Processing: Specialized agents with focused responsibilities

  • Task Distribution: Intelligent workload balancing across terminal sessions

  • Result Aggregation: Comprehensive output collection and analysis

  • Resource Management: Efficient terminal resource allocation

🛡️ Security First

  • Command Validation: Real-time security analysis before execution

  • Privilege Management: Safe execution with appropriate permissions

  • Sandbox Execution: Isolated command execution environments

  • Risk Assessment: Intelligent command risk scoring

📊 Terminal Management

  • Multi-Session Support: Concurrent terminal session management

  • Process Monitoring: Real-time process tracking and analysis

  • Performance Metrics: Terminal performance optimization

  • Logging System: Comprehensive command and output logging

💡 Intelligent Automation

  • Workflow Automation: Complex multi-step terminal workflows

  • Environment Detection: Automatic environment configuration

  • Dependency Resolution: Smart command dependency management

  • Error Handling: Robust error detection and recovery

Related MCP server: MCP Terminal

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/rnd-pro/terminal-x-mcp.git
cd terminal-x-mcp

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start the server
npm start

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "terminal-x-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-x-mcp/src/server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Basic Usage

// Example: Execute secure command workflow
await mcp.request("execute_command", {
  command: "npm install && npm test",
  security_level: "high",
  timeout: 60000
});

// Example: Monitor terminal processes
await mcp.request("monitor_processes", {
  filter: "node",
  metrics: ["cpu", "memory", "duration"]
});

🏗️ Architecture

Agent Communication Flow

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│ Terminal[X]MCP   │───▶│ Command Executor│
│  (Cursor/CLI)   │    │   Coordinator    │    │     Agent       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                        ┌───────┴───────┐
                        ▼               ▼
                ┌──────────────┐ ┌─────────────┐
                │Security      │ │Terminal     │
                │Monitor Agent │ │Monitor Agent│
                └──────────────┘ └─────────────┘
                        │               │
                        ▼               ▼
                ┌──────────────┐ ┌─────────────┐
                │Command       │ │Process      │
                │Validation    │ │Monitoring   │
                └──────────────┘ └─────────────┘

Multi-Agent Roles

  1. Terminal Coordinator Agent - Main command planning and orchestration

  2. Command Executor Agent - Safe command execution and output handling

  3. Security Monitor Agent - Command security analysis and validation

  4. Terminal Monitor Agent - Process monitoring and performance tracking

🛠️ Available Tools

Core Terminal Tools

  • execute_command - Secure command execution with validation

  • plan_workflow - Multi-step command workflow planning

  • monitor_processes - Real-time process monitoring

  • validate_security - Command security assessment

Agent Coordination Tools

  • coordinate_execution - Multi-agent command coordination

  • aggregate_outputs - Command output collection and analysis

  • manage_sessions - Terminal session management

Monitoring Tools

  • track_performance - Terminal performance metrics

  • analyze_logs - Command execution log analysis

  • monitor_resources - System resource monitoring

⚙️ Configuration

Environment Variables

# MCP Server Configuration
MCP_PORT=3003
NODE_ENV=development

# Agent Configuration
AGENT_MAX_CONCURRENCY=3
AGENT_TIMEOUT=30000

# Terminal Settings
TERMINAL_MAX_SESSIONS=10
TERMINAL_COMMAND_TIMEOUT=60000

# Security Configuration
SECURITY_VALIDATION_ENABLED=true
SECURITY_RISK_THRESHOLD=0.7

# Monitoring Settings
MONITORING_ENABLED=true
MONITORING_INTERVAL=5000

# Logging Configuration
LOG_LEVEL=info
LOG_TERMINAL_OUTPUT=true

🧪 Testing

# Run all tests
npm test

# Test multi-agent coordination
npm run test:agents

# Test terminal automation
npm run test:terminal

# Run security validation tests
npm run test:security

📁 Project Structure

terminal-x-mcp/
├── src/
│   ├── server/           # MCP server implementation
│   ├── agents/           # Multi-agent system
│   ├── core/            # Core functionality
│   └── utils/           # Utilities and helpers
├── test/                # Test suites
├── docs/                # Documentation
├── examples/            # Usage examples
└── assets/             # Assets and resources

🤝 Integration Examples

Command Workflow Automation

// Automated build and deploy workflow
const result = await terminalXMCP.executeWorkflow({
  commands: [
    "git pull origin main",
    "npm install",
    "npm run build",
    "npm run test",
    "npm run deploy"
  ],
  securityLevel: "high",
  failFast: true
});

Process Monitoring

// Monitor development server
const monitoring = await terminalXMCP.monitorProcess({
  command: "npm run dev",
  metrics: ["cpu", "memory", "network"],
  alertThresholds: {
    cpu: 80,
    memory: 1024
  }
});

🔮 Roadmap

Phase 1: Foundation ✅

  • Project structure setup

  • Basic MCP server implementation

  • Agent framework foundation

Phase 2: Core Agents (In Progress)

  • Terminal Coordinator implementation

  • Command Executor with security validation

  • Basic monitoring capabilities

Phase 3: Advanced Features

  • Multi-session terminal management

  • Advanced security monitoring

  • Workflow automation engine

Phase 4: Optimization

  • Performance optimization

  • Advanced command planning

  • Production deployment

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/rnd-pro/terminal-x-mcp.git
cd terminal-x-mcp

# Install dependencies
npm install

# Start development server
npm run dev

Submitting Changes

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-terminal-feature

  3. Commit changes: git commit -m 'Add amazing terminal feature'

  4. Push to branch: git push origin feature/amazing-terminal-feature

  5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

👥 Development Team

Developed by RND-PRO Team

  • 🌐 Website: rnd-pro.com

  • 💼 Professional development team specializing in innovative AI solutions

  • 🤖 Experts in multi-agent systems and terminal automation

  • 🚀 Leaders in MCP protocol implementations and secure command execution

🙏 Acknowledgments

  • Built on Model Context Protocol (MCP)

  • Inspired by multi-agent AI architectures and secure terminal automation

  • Command execution powered by Node.js process management

  • Security validation using advanced risk assessment algorithms

📞 Support

Made with ❤️ by RND-PRO Team for the terminal automation community

Available Tools

4 tools
execute_commandC

Execute a command in the terminal with security validation

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe command to execute
timeoutNoTimeout in milliseconds (default: 30000)
security_levelNoSecurity validation levelmedium
working_directoryNoWorking directory for command execution

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It mentions 'security validation' but does not elaborate on what that entails, potential side effects, failure modes, or resource impact. This is a significant gap for a tool that executes arbitrary commands, which is inherently risky.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with no redundancy. It efficiently communicates the core action. However, it is so brief that it omits crucial behavioral and usage details, which reduces its overall effectiveness. The brevity is not inherently flawed, but it sacrifices needed context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and risk (command execution with security validation), the description is grossly incomplete. It fails to explain return values, timeout behavior, working directory effects, security levels, or any failure handling. With no annotations and no output schema, this description carries the full burden and falls far short.

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 input schema provides complete descriptions for all four parameters, so the baseline is 3. The description adds no additional parameter-level meaning beyond what the schema already defines, and it doesn't clarify how 'security validation' relates to the security_level parameter.

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 tool's function: executing a command in the terminal. This is a specific verb+resource pairing. While it doesn't explicitly distinguish from siblings, the sibling tools (monitor_processes, validate_security, plan_workflow) serve obviously different purposes, so no ambiguity arises.

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 alternatives. It does not mention prerequisites, exclusions, or scenarios where another tool would be more appropriate. For a command execution tool, this lack of context leaves the agent without clear selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

monitor_processesC

Monitor running processes and collect metrics

ParametersJSON Schema
NameRequiredDescriptionDefault
filterNoFilter processes by name or pattern
metricsNoMetrics to collect
durationNoMonitoring duration in seconds

TDQS

C2.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to mention that monitoring is likely a read-only operation, whether any side effects occur, permission requirements, or return format. The description only states the basic action without any behavioral nuances.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no fluff, making it concise. However, it is under-specified for a 3-parameter tool and lacks structure. It is average: not overly verbose but also not providing enough useful content to be considered well-structured.

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?

Given no annotations and no output schema, the description must provide more context. It does not explain what the tool returns, how filtering works, or any limits on duration or metrics. The description is incomplete for a tool with three parameters.

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?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; 'collect metrics' relates to the metrics parameter but does not enrich understanding of filter or duration parameters. The schema already documents each parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs 'monitor' and 'collect' and identifies the resource as 'running processes' and metrics. It distinguishes itself from sibling tools like execute_command and validate_security, which have different purposes.

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?

There is no guidance on when to use this tool versus alternatives. The description is purely declarative and provides no context about appropriate scenarios, prerequisites, or situations where other tools should be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plan_workflowB

Plan a multi-step terminal workflow

ParametersJSON Schema
NameRequiredDescriptionDefault
goalYesThe workflow goal or objective
commandsNoList of commands to execute
dependenciesNoCommand dependencies and ordering

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden of behavioral disclosure. It does not explicitly state whether the tool executes commands or merely returns a plan, nor does it mention side effects or safety characteristics. The verb 'plan' implies non-execution, but this is not explicit.

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 a single sentence with no filler, directly stating the core purpose. It is appropriately concise and front-loaded.

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?

Given the nested dependencies parameter, lack of output schema, and presence of execution siblings, the description is too sparse. It does not explain return behavior, the dependencies field, or how planning relates to execution, leaving critical gaps for effective usage.

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% parameter description coverage, so the description does not need to add parameter details. It doesn't add extra meaning beyond the schema, which is the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description provides a specific verb ('plan') and resource ('multi-step terminal workflow'), clearly distinguishing it from sibling tools like execute_command, which executes commands rather than plans them.

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 offers no guidance on when to use this tool vs alternatives such as execute_command. It does not mention prerequisites, conditions for planning versus executing, or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_securityB

Validate command security and assess risk level

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesCommand to validate
contextNoExecution context information

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does not state whether the command is actually executed, how risk is assessed, or what side effects might occur. The agent is left with only a high-level 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 a single concise sentence, front-loaded with the primary verb and object, containing no fluff or redundant details.

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?

The tool has no output schema and no annotations, yet the description says nothing about return values, error conditions, or behavioral caveats. For a security validation tool, this is insufficient for an agent to anticipate results or side effects.

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?

Schema description coverage is 100%, so both parameters already have descriptions. The tool description adds no extra meaning beyond the schema, such as how 'context' influences validation or expected command formats. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('validate') and names the resource ('command security') plus an outcome ('assess risk level'), making its purpose clear. It naturally distinguishes from sibling tools like execute_command and monitor_processes.

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, when not to, or what alternatives exist. It simply states what it does without contextualizing its placement among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0-alpha.1
    • First observedexecute_command
    • First observedmonitor_processes
    • First observedplan_workflow
    • First observedvalidate_security
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: execute_command runs commands, monitor_processes observes processes, validate_security assesses command risk without executing, and plan_workflow designs multi-step sequences. The slight overlap between execute_command's built-in validation and validate_security is separated by execution vs assessment, so no real ambiguity exists.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: execute_command, monitor_processes, validate_security, plan_workflow. The verbs and nouns are clear and uniformly formatted, making the tool names predictable and easy to understand.

Tool Count5/5

With 4 tools, the server is well-scoped for its stated purpose of secure terminal interaction. Each tool covers a distinct phase (planning, validation, execution, monitoring) without redundancy or bloat, falling comfortably within the ideal 3-15 range.

Completeness3/5

The set covers core terminal operations but has notable gaps: no tool for process control (e.g., kill, stop), and plan_workflow only creates a plan without an execution mechanism to run the whole workflow at once. While execute_command can handle many actions, these missing operations limit the server's end-to-end workflow support.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Terminal

    sichang824
    A
    license
    C
    quality
    C
    maintenance
    A server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).
    3
    27
    MIT

  • mcp-server-terminal

    aybelatchane
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server enabling AI agents to interact with terminal applications through structured Terminal State Tree representation. Works with any AI assistant that supports the Model Context Protocol.
    53 npm
    19
    MIT

  • devir

    Davidkata1234
    A
    license
    Not graded
    quality
    C
    maintenance
    A command-line interface and MCP server for managing and monitoring multiple development services through a unified terminal UI. It enables users to interact with service logs, filter messages, and control development environments directly via Model Context Protocol integration.
    -