Simple Subprocess

A Python-based MCP server that executes shell commands via a subprocess bridge for LLM-driven workflows.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "yonaka15-simple-subprocess-mcp": {
      "command": "uv",
      "args": [
        "run",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

You set up a lightweight MCP server that executes arbitrary shell commands from an LLM application, using a simple subprocess bridge. It runs under Python and is invoked via the FastMCP ecosystem, giving you a practical way to interact with the host system through safe, bounded subprocess calls.

How to use

You interact with the server from an MCP client by starting the local subprocess MCP server and then issuing the run_command tool to execute shell commands. The system returns standard output on success and an error message on failure, including the exit code and error output. Use this to perform tasks like listing files, inspecting system information, or querying web resources, all from your LLM workflow.

How to install

Prerequisites: Python 3.11 or newer and the uv package manager.

# Install dependencies
uv sync

Run the server

Start the MCP server using one of the documented runtime commands. You can run it directly or via an alternate fastmcp path.

uv run python server.py

uv run fastmcp run server.py

Test the client

Verify the setup by running the test client that exercises the MCP endpoint.

uv run python test_client.py

Integrate with an MCP-enabled app

In your MCP-enabled application, such as Claude Desktop, add the server path to your configuration so the client can locate and communicate with the local server.

Additional notes

When you start the server, you may choose between the direct command or the fastmcp command depending on your environment. The server exposes a run_command API to execute shell commands from the client.

Security and safety considerations

This server can execute arbitrary shell commands, so limit its use to trusted environments. Apply sandboxing, command filtering, least-privilege execution, and robust logging to minimize risk.

Troubleshooting

If commands time out after 30 seconds, adjust the server timeout setting to accommodate longer operations. Ensure the client and server run with appropriate permissions to avoid permission errors.

Example workflows

# List all files in the current directory
ls -la

# Show system information
uname -a

Available tools

run_command

Executes a shell command provided by the client and returns the standard output on success or an error payload including the exit code and error output on failure.