tfbash-mcp
This server provides a set of persistent shell tools for agents to run and control command-line work across platforms.
Open persistent shells (
shell_open) with a chosen cwd and environment, returning a stableshell_id.Execute shell commands (
shell_exec) with configurable yield, timeout, and output size limits; short commands return immediately, long ones continue running.Read incremental command output (
shell_read) from a cursor for long-running executions.Write text to an active execution's stdin (
shell_write), e.g. for interactive prompts.Send portable control signals (
shell_signal) such asinterrupt,terminate, orkill.List all open shells (
shell_list) with runtime, host, and per-shell status/cwd/active execution info.Close shells (
shell_close) and clean up their managed process trees.Support multiple independent persistent shells, each preserving cwd, environment, and shell state.
Run on macOS, Linux, and Windows, auto-detecting Bash, Zsh, or PowerShell runtimes.
Expose tools through a stdio MCP server or an embedded Python async runtime for IDE/SDK hosts.
Provide a subscribable shell-overview resource for desktop UI display of shell and execution state.
Click on "Deploy 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., "@tfbash-mcp run 'df -h' to check disk usage"
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.
tfbash-mcp
A foundational MCP tool collection for Agent systems. The project aims to provide a set of stable, composable, low-cognitive-load general capabilities for different Agents, such as command execution, file read/write, and search; specific capabilities prioritize reusing mature implementations, only considering adaptation or in-house development when existing solutions cannot meet core constraints.
Current status: Python project skeleton with requirements/architecture RFC. The repository can start an empty stdio MCP Server, but does not yet provide the Shell tools defined in the RFC.
Why this project
Agents often need to leave pure text reasoning and operate on real workspaces or invoke local programs. Programmers use Shell as their primary work interface; general roles such as product, operations, and research also use Shell to call scripts, convert files, batch-process data, or diagnose environments.
Existing MCP tools vary greatly in capability scope and execution model: some only support one-shot commands, some depend on PTY or resident daemon processes, some have built-in approval and sandboxing, and some lack reliable long-command, incremental output, and managed process cleanup. tfbash-mcp first defines real scenarios and verifiable capability contracts, then decides whether to adopt directly, wrap/adapt, or build in-house.
Related MCP server: MCP Terminal Tool Server
Design Principles
Scenarios first, then technology selection: Don't reverse-engineer requirements from familiarity with a language, framework, or existing project.
Reuse first: Selection order is Adopt → Wrap → Build; reuse must be premised on meeting key behaviors.
Small and orthogonal: Keep clear boundaries for foundational tools, avoiding pushing Agent orchestration, business workflows, or UI into the tool layer.
Explicit state: Long-running tasks, persistent Shells, output cursors, exit status, and resource lifecycles should all be observable; Shells that need to preserve cwd/env must be explicitly created and addressed.
Protocol and implementation language agnostic: Tool contracts do not expose Python, pexpect, Computer, or client internals; V1 uses Python + pexpect and stdio transport.
Trust the deployment environment: Phase 1 does not include built-in approval, sandbox, command policy, or directory boundaries.
Controllable resources: Memory, disk, sessions, processes, and temporary files must have clear limits, ownership, and cleanup rules.
Phase 1: Bash Tools
Phase 1 focuses on a standalone general-purpose Bash MCP Server for Unix environments (Linux, macOS). The goal covers simultaneously:
Programmers' build, test, code search, service startup, and log observation;
General roles using installed CLIs or scripts for file processing, data transformation, and environment diagnostics;
Multiple addressable persistent Command Shells that each preserve cwd, environment, and activation state, and return accurate exit status for each command;
pexpect PTY's stdout/stderr returned as combined output, with bounded incremental output maintained for each execution;
Short commands returned once by
shell_exec; long commands exceedingyield_msreturnrunningand continue executing in the original Shell;Long commands read incrementally via
shell_read, write to stdin viashell_write, and interrupt or terminate viashell_signal;Persistent Command Shells support create, execute, incremental read, write, signal, list, and close, no longer exposing separate background Job and Terminal tool groups;
Shells and Executions belong to the MCP service process and persist across tool calls, but recovery across service restarts is not promised;
One tfrobot-client Computer corresponds to one SDK-managed MCP process; the client only keeps the enable toggle and running state.
Phase 1 persistent Shells will use PTY, but only provide command-oriented text streams, not full-screen TUI screen models, raw terminal Sessions, or resize. If a clear integration party for xterm.js, REPL, or full-screen TUI emerges later, Terminal mode will be added on the same Shell resource model. Also not included: command approval, process sandboxing, cross-service restart recovery, and strong coupling with MCP Tasks.
Related documentation:
General Bash MCP Server Requirements and Architecture: defines standalone MCP boundaries, tool contracts, ide4ai reuse scope, SDK/client responsibilities, and acceptance criteria.
Planned Foundational Capabilities
The current roadmap only expresses exploration order, not a decision to build in-house:
Persistent Shell and long-command Execution;
File read, write, and patch-style modification;
File discovery and text search;
Other small foundational tools added based on real Agent workflows.
Each capability should first form independent requirements and candidate research, and record the Adopt, Wrap, or Build decision rationale. Different capabilities can use different sources, as long as the error model, lifecycle, and result structure exposed to Agents remain consistent.
Repository Structure
.
├── .github/workflows/tests.yml # Python 3.10–3.12 CI
├── pyproject.toml # 包元数据、依赖与工具配置
├── src/tfbash_mcp/ # MCP Server 包与入口
├── tests/ # 自动化测试
├── README.md
├── docs/
│ └── bash-tool-requirements.md
└── reference/
├── ide4ai/ # pexpect 持久 Shell 基线
├── codex/ # 进程生命周期参考
├── pi/ # Agent Shell 参考
└── deepseek-harness/ # Agent Runtime 参考reference/ is a local research checkout directory, large in size and containing multiple third-party Git repositories, so it will not be included in tfbash-mcp's version control or distribution packages.
Local Development
The project supports Python 3.10–3.12 and uses uv to manage the environment:
uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --covStart the current stdio Server skeleton:
uv run tfbash-mcpThis process does not register Shell tools yet; it is only used to verify the package, entry point, and MCP stdio lifecycle.
Participation Decisions
The requirements document has already determined the V1 multi-Shell + Execution tool model and the Python/pexpect implementation baseline, but it is still an unimplemented, unaccepted RFC. Before entering development, at least the following is needed:
Align on the hard thresholds and open items in the document;
Run minimal feasibility experiments on the selected pexpect baseline;
Confirm the license retention method, adaptation cost, long-term maintenance surface, and exit strategy for ide4ai code extraction;
Write back the experiment results and final implementation deviations to the RFC, then enter coding and acceptance.
Available Tools
7 toolsshell_closeA
Close a persistent shell and its managed process tree.
Inputs: shell_id (required). Returns: status, shell_id, cleanup_complete
shell_execC
Execute one bash command in a persistent shell.
Inputs: command (required), shell_id (required), yield_ms, timeout_ms, +1 more. Returns: object
shell_listA
List shells with authoritative runtime and redacted host context.
Inputs: no named parameters. Returns: host, shells, runtime
shell_openC
Open a persistent bash command shell.
Inputs: cwd, env, startup_command. Returns: cwd, status, dialect, shell_id
shell_readC
Read incremental output from an execution cursor.
Inputs: cursor (required), exec_id (required), shell_id (required), wait_ms, +1 more. Returns: object
shell_signalC
Send a portable control intent to the active execution.
Inputs: signal (required), exec_id (required), shell_id (required). Returns: signal, status, exec_id, shell_id
shell_writeC
Write UTF-8 text to the active execution.
Inputs: text (required), exec_id (required), shell_id (required). Returns: status, exec_id, shell_id, accepted_bytes
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct operation in the shell lifecycle: creating, executing, reading, writing, signaling, listing, and closing. There is no meaningful overlap between the tool purposes, and the descriptions make the boundaries clear.
All tool names follow the exact same shell_verb pattern, making the API highly predictable. The verb choice is consistent and matches the corresponding action with no style mixing.
Seven tools is well-scoped for a persistent bash shell server. Each tool covers a necessary aspect of shell interaction without redundancy or bloat.
The toolset covers the full lifecycle of a persistent shell: open, execute, read output, write input, send signals, list shells, and close. There are no obvious dead ends or missing operations for the stated domain.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables coding agents to execute and manage long-running shell commands asynchronously with capabilities for process monitoring, interaction, and lifecycle management.741 PyPI14MIT
- FlicenseBqualityDmaintenanceAn MCP server that enables users to execute arbitrary shell commands on their local machine and receive the output. It provides a terminal tool for running system commands through MCP-compatible clients using the Python SDK.1-
- AlicenseBqualityBmaintenanceA secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.13137 npm6MIT
- AlicenseNot gradedqualityBmaintenanceA PTY-based MCP server providing persistent, interactive shell sessions with strong Windows support, enabling AI agents to run commands, handle interactive tools, and manage large output across MCP-compatible clients.202 npm12MIT