Create Standalone Code Execution MCP With Agent Zero
This article will guide you through the process of creating a standalone Model Context Protocol (MCP) server using Agent Zero's powerful code execution capabilities. We'll focus on building a minimal, self-contained package that leverages existing Agent Zero code, ensuring a streamlined and efficient solution. If you are looking to execute terminal commands and python code in a secure and controlled environment, this guide is for you. Let's dive in and see how you can easily set this up!
Overview: Building a Standalone MCP
The primary goal here is to package Agent Zero's code execution tool into a standalone MCP. This MCP will enable agents to execute terminal commands and Python code on a host system via standard input/output (stdio) communication. Think of it as creating a mini-application that provides a specific function without needing the full Agent Zero environment. This approach is perfect for scenarios where you need a lightweight, isolated code execution environment.
The key is to reuse as much of the existing Agent Zero code as possible. We're not reinventing the wheel; we're simply repackaging it for a specific purpose. This minimizes the risk of introducing bugs and ensures that we benefit from the robustness of Agent Zero's battle-tested components.
Architecture Pattern: Following Agent Zero's Lead
To ensure consistency and maintainability, we'll adhere strictly to Agent Zero's established architectural patterns. This means:
- Keeping helper modules unchanged wherever feasible.
- Preserving the
print_style
andlog
utilities. - Using the established
tty_session
andshell_local
architecture. - Maintaining the core logic of the code execution tool.
By sticking to these patterns, we ensure that our standalone MCP integrates seamlessly with existing Agent Zero workflows and remains easy to understand and maintain. This approach also simplifies troubleshooting and future updates.
Package Structure: Organizing Our MCP
The standalone MCP will have a well-defined directory structure, making it easy to navigate and manage. Here's the layout:
code-execution-mcp/
├── main.py # MCP server entry point
├── code_execution_tool.py # Stripped version of Agent Zero's tool
├── helpers/
│ ├── tty_session.py # Copy as-is
│ ├── shell_local.py # Copy as-is
│ ├── print_style.py # Copy as-is
│ ├── log.py # Minimal placeholder version
│ └── strings.py # Copy as-is
├── prompts/
│ ├── fw.code.info.md # Copy as-is
│ ├── fw.code.no_output.md # Copy as-is
│ ├── fw.code.max_time.md # Copy as-is
│ ├── fw.code.no_out_time.md # Copy as-is
│ ├── fw.code.pause_time.md # Copy as-is
│ ├── fw.code.pause_dialog.md # Copy as-is
│ └── fw.code.reset.md # Copy as-is
├── pyproject.toml # Package definition
└── README.md # Usage instructions
Let's break down each component:
main.py
: This is the entry point for our MCP server. It initializes the server, registers the tools, and handles communication.code_execution_tool.py
: A stripped-down version of Agent Zero's code execution tool, tailored for standalone use.helpers/
: This directory contains helper modules, includingtty_session.py
,shell_local.py
,print_style.py
,log.py
, andstrings.py
. These modules provide essential functionalities for terminal session management, output formatting, and logging.prompts/
: This directory holds markdown prompt files used by the code execution tool.pyproject.toml
: This file defines the package metadata and dependencies.README.md
: This file provides instructions on how to use the MCP.
File Specifications: Diving into the Details
Now, let's take a closer look at each file and its role in the standalone MCP.
1. main.py
: The MCP Server Entry Point
main.py
is the heart of our standalone MCP. It's responsible for initializing the MCP server, registering the tools, and handling communication via stdio. Here's what it does:
- Initializes the MCP server with stdio transport using the
fastmcp
package. - Registers four core tools:
execute_terminal
,execute_python
,get_output
, andreset_terminal
. These tools expose the code execution capabilities of our MCP. - Reads configuration from environment variables or stdin, allowing for flexible setup.
- Each tool calls corresponding methods in the
CodeExecutionTool
class, delegating the actual execution logic. - Crucially, there's no networking involved. All communication happens via stdio, keeping the MCP lightweight and secure.
The configuration structure supports the following parameters:
{
"executable": "/bin/bash",
"init_commands": ["source /venv/bin/activate"],
"options": {
"first_output_timeout": 30,
"between_output_timeout": 15,
"dialog_timeout": 5,
"max_exec_timeout": 180
}
}
executable
: The path to the shell executable (e.g.,/bin/bash
orcmd.exe
).init_commands
: A list of commands to execute when a new shell session is created (e.g., activating a virtual environment).options
: A dictionary of timeout settings, includingfirst_output_timeout
,between_output_timeout
,dialog_timeout
, andmax_exec_timeout
. These timeouts help prevent runaway processes and ensure the MCP remains responsive.
2. code_execution_tool.py
: The Stripped-Down Execution Engine
This file is a modified version of Agent Zero's code execution tool, optimized for standalone operation. The goal is to remove unnecessary dependencies and features while retaining the core functionality.
What we remove:
- All SSH-related code, as we're focusing on stdio communication.
- All NodeJS-related code, simplifying the execution environment.
- Agent context dependencies (references to
self.agent
), making the tool more self-contained. - Tool base class inheritance, as we don't need the complexity of a larger framework.
handle_intervention
calls, streamlining the execution flow.
What we keep:
- All terminal session management logic, ensuring we can handle multiple sessions effectively.
- Python execution via IPython, allowing agents to run Python code.
- Terminal command execution, enabling agents to interact with the underlying system.
- Output reading with all timeout logic, crucial for preventing hangs and ensuring timely responses.
- Reset terminal functionality, allowing agents to clear sessions and start fresh.
- Session management (the
shells
dictionary), tracking active terminal sessions. - Prompt detection patterns, used to identify when a command has finished executing.
- Output formatting and truncation, ensuring responses are concise and readable.
What we modify:
- Replace
self.agent.read_prompt()
calls with direct file reading from theprompts/
directory. This eliminates the dependency on the Agent Zero context. - Replace
self.agent.config
references with init parameters (executable, init_commands, timeouts). This makes the tool configurable without relying on a global configuration object. - Replace
self.agent.context.log
with a minimal log placeholder, as we don't need full-fledged logging in this standalone setup. - Make the
State
class hold theshells
dictionary and configuration, centralizing session management. - Initialize
LocalInteractiveSession
with a configurable executable instead of hardcoding/bin/bash
. This allows users to specify their preferred shell.
3. helpers/tty_session.py
: Terminal Session Management
This file is copied as-is from Agent Zero. It provides the core logic for managing terminal sessions, including handling input, output, and signals. No modifications are needed, as it's already designed to be standalone.
4. helpers/shell_local.py
: Local Shell Interaction
This file is also copied from Agent Zero, with one crucial modification: the __init__
method is changed to accept an executable
parameter instead of hardcoding /bin/bash
. This allows us to specify the shell executable via the MCP configuration.
5. helpers/print_style.py
: Output Formatting and Logging
This file is copied as-is from Agent Zero. It provides utilities for formatting output and logging messages. We keep all functionality, including log file creation, as the MCP server can write to its own log file for debugging and monitoring.
6. helpers/log.py
: Minimal Logging Placeholder
In this standalone MCP, we don't need a full-fledged logging system. However, the code_execution_tool.py
still references logging functions. To avoid errors, we create a minimal placeholder version of log.py
.
This placeholder includes only the Log
and LogItem
classes with their signatures. All methods are no-ops or return empty values. This allows the code_execution_tool.py
to call self.log.update()
without issues, while effectively disabling logging.
7. helpers/strings.py
: Text Manipulation Utilities
This file is copied as-is from Agent Zero. It provides utilities for text manipulation, such as truncation, which are used by the code_execution_tool.py
to ensure responses are concise and readable.
8. Prompt Files: System Messages
We copy all seven markdown prompt files from Agent Zero's prompts/
directory. These files contain system messages that are returned to the agent in various scenarios, such as when a command times out or produces no output. By including these files, we ensure that our standalone MCP behaves consistently with Agent Zero.
MCP Tool Definitions: Exposing Functionality
Our standalone MCP exposes four core tools:
Tool 1: execute_terminal
This tool allows agents to execute terminal commands in a specified session.
{
"name": "execute_terminal",
"description": "Execute a terminal command in the specified session",
"inputSchema": {
"type": "object",
"properties": {
"command": {"type": "string"},
"session": {"type": "integer", "default": 0}
},
"required": ["command"]
}
}
Tool 2: execute_python
This tool allows agents to execute Python code via IPython in a specified session.
{
"name": "execute_python",
"description": "Execute Python code via IPython in the specified session",
"inputSchema": {
"type": "object",
"properties": {
"code": {"type": "string"},
"session": {"type": "integer", "default": 0}
},
"required": ["code"]
}
}
Tool 3: get_output
This tool allows agents to retrieve accumulated output from a terminal session.
{
"name": "get_output",
"description": "Get accumulated output from a terminal session",
"inputSchema": {
"type": "object",
"properties": {
"session": {"type": "integer", "default": 0}
}
}
}
Tool 4: reset_terminal
This tool allows agents to reset a terminal session, closing and reopening it.
{
"name": "reset_terminal",
"description": "Reset a terminal session, closing and reopening it",
"inputSchema": {
"type": "object",
"properties": {
"session": {"type": "integer", "default": 0}
}
}
}
Dependencies: Defining Our Requirements
Our standalone MCP has a few dependencies, which are defined in the pyproject.toml
file:
[project]
name = "code-execution-mcp"
version = "0.1.0"
dependencies = [
"fastmcp>=2.0.0",
"ipython>=8.0.0",
"asyncio",
"nest_asyncio",
]
[project.optional-dependencies]
windows = ["pywinpty>=2.0.0"]
[project.scripts]
code-execution-mcp = "main:main"
fastmcp
: The library for creating MCP servers.ipython
: The interactive Python shell, used for executing Python code.asyncio
andnest_asyncio
: Libraries for asynchronous programming.pywinpty
(optional): A library for terminal emulation on Windows.
Implementation Notes: Key Considerations
Session Management
We use Agent Zero's existing session dictionary pattern to manage multiple terminal sessions. Each session maintains its own shell state, allowing agents to run commands and code in isolation.
Executable Configuration
We default to /bin/bash
on Unix-like systems and cmd.exe
on Windows. However, users can override this via the MCP configuration, allowing them to specify their preferred shell.
Init Commands
The MCP supports executing a list of initialization commands when a new session is created. This is useful for tasks such as activating virtual environments or setting environment variables.
Timeout Configuration
We map timeout options from the MCP configuration to the code execution tool's parameters, allowing users to control the execution time of commands and code.
Output Handling
We ensure that all output returned by the MCP is clean and free of control codes. We also use Agent Zero's truncation logic to limit the size of responses.
Python Execution
We execute Python code via the ipython -c
command, ensuring proper escaping of special characters. We also add a python>
prefix to the output for clarity.
Windows Compatibility
The tty_session
module already handles Windows via pywinpty
. We default to cmd.exe
on Windows and include pywinpty
as an optional dependency.
Critical Don'ts: Staying on Track
To ensure we build a focused and maintainable MCP, it's crucial to avoid certain pitfalls:
- DO NOT implement new shell/TTY logic. Use Agent Zero's tested implementation.
- DO NOT add any networking/HTTP capabilities. Sticking to stdio is key.
- DO NOT create new logging systems. The existing
print_style
is sufficient. - DO NOT add configuration validation beyond basic type checks.
- DO NOT implement authentication/security. The MCP client is responsible for this.
- DO NOT add progress bars, spinners, or UI elements. Keep it simple.
- DO NOT create custom exception types. Use standard Python exceptions.
- DO NOT add caching/optimization layers. Focus on functionality first.
- DO NOT implement plugin systems or extensibility hooks. This is a standalone tool.
- DO NOT write any code not directly from Agent Zero or required for MCP glue.
Testing Considerations: Ensuring Quality
Virtual Environment Behavior
When the MCP is launched from a virtual environment, the shell session may not inherit the environment activation. Users should use init_commands
to explicitly activate the virtual environment if needed. This behavior should be clearly documented in the README.
Windows Testing
The tty_session
module uses pywinpty
, which should work on Windows but is not thoroughly tested in this context. Windows support should be considered experimental, and users should be encouraged to test with cmd.exe
and PowerShell.
Success Criteria: Defining Done
We'll consider the standalone MCP a success when it meets the following criteria:
- The MCP server starts via stdio without errors.
- All four tools are discoverable via MCP
list_tools
. - Terminal commands execute and return output.
- Python code executes via IPython.
- Multiple sessions work independently.
- Reset clears the session and starts fresh.
- Timeouts work as configured.
- Output is clean (no ANSI codes in responses).
- Init commands execute on session creation.
- Works on Linux (tested) and Windows (untested but should work).
Notes: Key Takeaways
- This MCP allows any agent to execute code on the host system.
- Security is the MCP client's responsibility, not the server's.
- The implementation should be under 500 lines of code (excluding copied helpers).
- The goal is to expose existing functionality, not recreate it.
- We should preserve all of Agent Zero's battle-tested code execution logic.
- The only "new" code is the MCP server glue in
main.py
.
Conclusion
Creating a standalone code execution MCP with Agent Zero is a powerful way to leverage existing functionality in a focused and efficient manner. By following the guidelines outlined in this article, you can build a minimal, self-contained package that enables agents to execute terminal commands and Python code securely and reliably. This approach is ideal for scenarios where you need a lightweight code execution environment without the overhead of a full Agent Zero deployment. By reusing existing code and adhering to established patterns, you'll create a solution that is easy to maintain, troubleshoot, and integrate into your workflows. So go ahead, start building your standalone MCP and unlock the power of Agent Zero's code execution capabilities!