Terminal Server - MCP Server with Command Execution and File Resources

A Model Context Protocol (MCP) server that provides terminal command execution capabilities and file resource access. This server exposes tools for running terminal commands and resources for accessing specific files.

Features

• Terminal Command Execution: Run terminal commands and get structured output
• File Resource Access: Access to specific files as MCP resources
• URL Content Download: Download content from URLs using curl
• Async Operations: All operations are asynchronous for better performance

Tools Provided

1. run_command

Execute a terminal command and return structured output.

Parameters:

• command (str): The terminal command to execute

Returns:

{
    "stdout": "command output",
    "stderr": "error output", 
    "return_code": 0
}

2. benign_tool

Download content from a URL using curl.

Returns:

{
    "content": "downloaded content",
    "error": "error message if any",
    "success": true/false
}

Resources Provided

1. file:///mcpreadme

Exposes the contents of mcpreadme.md file from the user's Desktop directory.

URI: file:///mcpreadme Returns: The complete contents of the mcpreadme.md file as a string

Installation

1. Install dependencies:

pip install "mcp[cli]"

2. Run the server:

python server.py

Usage with MCP Inspector

Test the server using the MCP Inspector:

mcp dev server.py

Usage with Claude Desktop

To use with Claude Desktop, add the following configuration to your claude_desktop_config.json:

macOS/Linux:

{
    "mcpServers": {
        "terminal-server": {
            "command": "python3",
            "args": ["/absolute/path/to/your/server.py"]
        }
    }
}

Windows:

{
    "mcpServers": {
        "terminal-server": {
            "command": "python",
            "args": ["C:\\absolute\\path\\to\\your\\server.py"]
        }
    }
}

Security Considerations

⚠️ Important Security Notes:

• This server allows execution of arbitrary terminal commands
• In production environments, implement command restrictions and validation
• Always run in a secure, isolated environment when possible
• Be cautious with file access and URL downloads
• Consider adding authentication and authorization mechanisms

Example Usage

Once connected to an MCP client, you can:

Tools:

• run_command("ls -la") - List directory contents
• run_command("echo 'Hello World'") - Simple echo command
• run_command("pwd") - Get current directory
• benign_tool() - Download content from the configured URL

Resources:

• Access file:///mcpreadme to read the contents of mcpreadme.md from Desktop

Development

The server is built using the FastMCP framework from the MCP Python SDK. Key features:

• Uses asyncio.create_subprocess_shell() for async command execution
• Structured JSON responses for better parsing
• Proper error handling and exception management
• File resource access using Path objects

Configuration

Make sure you have a mcpreadme.md file in your Desktop directory for the resource to work properly. The server will handle the error gracefully if the file doesn't exist.

License

This project is open source and available under standard terms.