How do I use bash-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bash-mcp start a background process for npm run dev" 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.

bash-mcp

by tinywind

Overview Schema Related Servers Score Discussions

JavaScript

Local

bash-mcp

A simple MCP (Model Context Protocol) server that enables Claude to execute shell commands without permission prompts.

⚠️ Security Warning: This server executes arbitrary shell commands. Use with caution and only in trusted environments.

Installation

# Install globally
npm install -g bash-mcp

# Or use with npx
npx bash-mcp

Related MCP server: Shell Exec MCP

Quick Start

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bash": {
      "command": "npx",
      "args": ["bash-mcp"]
    }
  }
}

For Claude Code (Cursor, VS Code)

Open command palette (Cmd/Ctrl + Shift + P)
Run "MCP: Add Server"
Select "NPM" as the server type
Enter: bash-mcp

Available Tools

`run` - Execute a command

// Simple command
run("ls -la")

// With working directory
run("npm test", { cwd: "/path/to/project" })

// With timeout (milliseconds)
run("long-running-command", { timeout: 60000 })

`run_background` - Start a background process

// Start a dev server
run_background("npm run dev", "frontend")

// Start backend service with working directory
run_background("./gradlew bootRun", "backend", { cwd: "./backend" })

`kill_background` - Stop a background process

kill_background("frontend")

`list_background` - List all background processes

list_background()

Example Usage

User: Start the development servers
Assistant: I'll start both frontend and backend servers for you.

[Uses run_background tool]
Started frontend server (PID: 12345)
Started backend server (PID: 12346)

User: Check if they're running
Assistant: [Uses list_background tool]
Both servers are running successfully!

Response Format

All tools return JSON formatted responses:

{
  "success": true,
  "stdout": "command output",
  "stderr": "error output if any",
  "command": "executed command"
}

For background processes:

{
  "success": true,
  "name": "frontend",
  "pid": 12345,
  "command": "npm run dev",
  "message": "Started background process 'frontend' (PID: 12345)"
}

Features

Execute any shell command without permission prompts
Run long-running processes in the background
Manage background processes (list, kill)
Capture stdout and stderr
Set working directory for commands
Configure timeout for commands
Automatic cleanup on server shutdown
NEW: Automatic output truncation with full output saved to temp files
NEW: Configurable output size limits and temp directory via environment variables

Environment Variables

BASH_MCP_MAX_OUTPUT_SIZE: Maximum output size in bytes before truncation (default: 51200/50KB)
BASH_MCP_TEMP_DIR: Directory for storing full output when truncated (default: system temp directory)

Example Configuration

{
  "mcpServers": {
    "bash": {
      "command": "npx",
      "args": ["bash-mcp"],
      "env": {
        "BASH_MCP_MAX_OUTPUT_SIZE": "102400",
        "BASH_MCP_TEMP_DIR": "/tmp/bash-mcp-outputs"
      }
    }
  }
}

Output Overflow Handling

When command output exceeds BASH_MCP_MAX_OUTPUT_SIZE:

Output is truncated to the specified limit
Full output is saved to a temporary file
The response includes the file path where full output can be found
If custom temp directory fails, falls back to system temp directory

Security Considerations

This MCP server executes arbitrary shell commands with the same privileges as the Node.js process. Only use in development environments or trusted contexts.

Requirements

Node.js >= 16.0.0
npm or npx

License

MIT

Author

tinywind tinywind0@gmail.com

Contributing

Issues and pull requests are welcome at GitHub.

Available Tools

4 tools

kill_backgroundA

Kill a background process by name

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	Name of the background process to kill

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It only states the action and target, but does not disclose side effects (e.g., irreversible process termination), behavior when the process is not found, or whether it uses a graceful shutdown. This is insufficient for a destructive tool.

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, front-loaded sentence with no unnecessary words. It is appropriately concise for the tool's simplicity.

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

Completeness3/5

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

For a simple 1-parameter tool, the description covers the core action, but it lacks context about return values (no output schema) and edge-case behaviors. Given the destructive nature, additional guidance would improve completeness.

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 already documents the 'name' parameter with a clear description, so the description's phrase 'by name' adds no new information. Baseline 3 applies due to 100% 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 uses a specific verb ('Kill') with a clear resource ('background process') and a qualifier ('by name'). It clearly distinguishes from sibling tools like run and list_background, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit usage guidance is provided. The context implies it's for stopping background processes, but the description does not mention alternatives or exclusions, so usage must be inferred from the name and sibling tools.

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

list_backgroundA

List all running background processes

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It clearly implies a read-only operation via 'list', but it does not disclose details such as the return format, whether it includes process IDs, or any side effects. For a simple list operation, this is adequate but not rich.

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, clear sentence that directly states the tool's function without any unnecessary words. It is front-loaded and easy to parse.

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

Completeness4/5

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

For a tool with no parameters and no output schema, the description is nearly complete. It clearly names the operation and scope, but it does not specify what the response contains (e.g., process names, IDs), which could be helpful. Given the tool's simplicity, this minor gap is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, and the schema description coverage is 100%, so the baseline is 4. The description adds no parameter details, but none are needed because there are no parameters to describe.

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 states exactly what the tool does: list all running background processes. The verb 'list' is specific and clearly distinguishes it from sibling tools like run, run_background, and kill_background, which perform different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for when you want to see running background processes, but it does not explicitly contrast with sibling tools or state when not to use it. There is no mention of alternatives or exclusions, so guidance is implied rather than explicit.

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

runC

Execute a shell command and return output

ParametersJSON Schema

Name	Required	Description
`cwd`	No	Working directory (optional)
`command`	Yes	Shell command to execute
`timeout`	No	Timeout in milliseconds (default: 30000)

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only says 'return output' but does not mention how stderr/stdout are handled, exit codes, side effects, environment variables, or whether the command runs in a sandbox. This is a significant gap for a shell execution tool.

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 sentence, front-loaded, and contains no fluff. It is concise but arguably too terse to be fully helpful. Every word earns its place, though more content would be beneficial.

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 is simple but has nuanced behavior (output format, timeout implications, working directory) and an important sibling relationship with run_background. The description does not explain these contextual aspects, and there is no output schema to clarify what is returned. Leaves significant gaps.

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 coverage is 100%, so parameter descriptions already document command, cwd, and timeout. The description adds no additional semantic value beyond the schema. Baseline 3 is appropriate because the schema carries the heavy lifting.

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?

Identifies the action as executing a shell command and returning output. The verb 'execute' and resource 'shell command' are specific, and 'return output' implies a foreground/synchronous operation, distinguishing it from the background sibling tools.

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?

No guidance about when to use this tool versus alternatives like run_background. Does not state that this runs in the foreground, blocks for completion, or is appropriate for commands that need immediate output. Lacks any context about selection criteria.

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

run_backgroundB

Run a command in background

ParametersJSON Schema

Name	Required	Description
`cwd`	No	Working directory (optional)
`name`	Yes	Unique name for this background process
`command`	Yes	Command to run in background

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose side effects. It states the command is run in background but does not mention that it executes arbitrary system commands, whether it returns immediately, how output is handled, or what resources are consumed. This lack of transparency is risky for a command execution tool.

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 that directly states the tool's purpose with no redundant words. It is front-loaded and efficient.

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 tool has no annotations or output schema, the description is too thin. It does not explain the background execution model (immediate return?), how to monitor or retrieve output, or implications of running arbitrary commands. Simple but incomplete.

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 provides 100% coverage with descriptions for all three parameters (command, name, cwd), so the baseline is 3. The description adds no additional parameter meaning, but the schema already defines them well.

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 ('Run') and resource ('command in background'), clearly distinguishing it from sibling tools (run, kill_background, list_background). It conveys exactly what action is performed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a use case (commands that should run in the background) but does not explicitly state when to use this tool over alternatives like 'run' or how it relates to kill/list_background. No exclusions or alternative names are mentioned.

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. Dates show when Glama detected each change.

4 tool updatesv1.1.0Aug 2, 2026
- First observedkill_background
- First observedlist_background
- First observedrun
- First observedrun_background

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation5/5

Each tool has a distinct purpose: run executes synchronously, run_background launches asynchronously, list_background inspects, and kill_background terminates. No overlapping actions or ambiguous boundaries.

Naming Consistency5/5

All tools follow a clear verb-based pattern: run, run_background, kill_background, list_background. The _background suffix consistently identifies async operations while the base verbs are predictable.

Tool Count5/5

Four tools provide a focused, minimal interface for shell command execution. This is well-scoped for the stated purpose, covering the essential lifecycle without unnecessary bloat.

Completeness5/5

The tool set covers the full lifecycle of background processes: start (run_background), inspect (list_background), and terminate (kill_background), along with synchronous execution (run). No obvious dead ends or missing operations for a basic bash server.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp AOAuth
dev.aicommander
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Shell Access Command Line OS Automation
2
SentinelX MCPOAuth
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
26
browser-ssh
com.browserssh
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Shell Access File Systems
2
termalin-web A
in.termal
Run commands and read/write files on your servers over Termalin's keyless tunnels (hosted MCP).
Shell Access File Systems
81

Related MCP Servers

Dynamic Shell Command MCP
Shell Access Command Line Security
b48f8f5xg2-blip
A
license
Not graded
quality
C
maintenance
Enables secure execution of shell commands through a dynamic approval system that prompts for user authorization on first use, with persistent command storage and comprehensive audit logging.
Updated 4 months ago (2026-05-03 17:10 UTC)
Apache 2.0
Shell Exec MCP
Shell Access Command Line OS Automation
domdomegg
A
license
Not graded
quality
C
maintenance
Enables execution of bash commands with support for timeouts and background jobs, allowing file operations, build commands, system inspection, and long-running tasks.
Updated 25 days ago (2026-08-12 00:51 UTC)
72
8
MIT
Run Command MCP Server
Shell Access Command Line OS Automation
stilllovee
A
license
Not graded
quality
D
maintenance
Provides tools for executing shell commands both synchronously and asynchronously with real-time output streaming and process management capabilities. It enables users to start background tasks, monitor progress, and manage long-running processes via Stdio or HTTP transports.
Updated 8 months ago (2026-01-14 04:20 UTC)
225
MIT
mcp-system
Shell Access Command Line OS Automation
MikeyBeez
F
license
B
quality
C
maintenance
Enables system automation and control including command execution, process management, network tools, environment variables, disk usage, and service status.
Updated 6 days ago (2026-08-31 01:38 UTC)
11
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tinywind/bash-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

bash-mcp

Installation

Quick Start

For Claude Desktop

For Claude Code (Cursor, VS Code)

Available Tools

run - Execute a command

run_background - Start a background process

kill_background - Stop a background process

list_background - List all background processes

Example Usage

Response Format

Features

Environment Variables

Example Configuration

Output Overflow Handling

Security Considerations

Requirements

License

Author

Contributing

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

`run` - Execute a command

`run_background` - Start a background process

`kill_background` - Stop a background process

`list_background` - List all background processes