Loading repository data…
uditk2 / repository
Local MCP server that runs shell/bash commands on your machine — a run_bash tool for Claude Desktop & Cowork over stdio or streamable-HTTP. Python, FastMCP, MIT.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
Cowork (and Claude Desktop) run in a sandbox and can't execute commands on your
own machine. This server bridges that gap — it connects Cowork to your local
bash so Claude can run shell commands directly on your computer, then read
their output.
A tiny Model Context Protocol server that lets
an MCP-aware client run shell commands on your local machine. It exposes one
tool, run_bash, and communicates over stdio.
From the client's side, running a command is just a tool call. On this side, the
command runs via bash -c with your user's permissions, and its exit code,
stdout, and stderr are returned.
By default this is an open shell: whatever connects can run anything you can. Only connect clients you trust, and consider using the allowlist below.
Download mcp-bash-server.mcpb and double-click it. Claude Desktop opens an
install dialog — review the permissions, optionally set an allowlist and default
working directory, and click Install. That's it: no Terminal, no pip, no
config files. Claude Desktop manages the runtime for you, and because the server
is registered locally, it also becomes available inside Cowork sessions.
An
.mcpb(MCP Bundle) is the one-click install format for local MCP servers, like a browser extension. This bundle uses theuvruntime, so you don't even need Python pre-installed.
The rest of this README is the manual route, for development or if you'd rather run it yourself.
bash on your PATHcd mcp-bash-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
The server supports two transports:
python server.py # stdio (default) — for the Claude Desktop bridge
python server.py --transport http # HTTP — serves MCP at http://127.0.0.1:8001/mcp
Selected from shared topics, language and repository description—not editorial ratings.
MCPStar /
🚀 A curated list of awesome Desktop Extensions (DXT) and MCP servers for Claude Desktop. Discover, share, and contribute to the growing ecosystem of AI-powered local tools and automations.
68/100 healtheshitakundu /
An MCP server that gives Claude Desktop structured access to your notes and past papers. Discovers topics, teaches in any style, quizzes you on grounded content, extracts PYQ patterns, and tracks mastery in local SQLite. Built with the official MCP Python SDK + FastMCP.
70/100 health--host / --port.Add an entry to your claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"bash": {
"command": "/absolute/path/to/mcp-bash-server/.venv/bin/python",
"args": ["/absolute/path/to/mcp-bash-server/server.py"]
}
}
}
Use absolute paths. Restart Claude Desktop; the run_bash tool should appear.
If you'd rather register it by URL (e.g. for Cowork's custom connector flow), run the HTTP transport and point the connector at it:
python server.py --transport http --port 8001
# -> serves http://127.0.0.1:8001/mcp
Then add a custom connector with URL http://localhost:8001/mcp. To keep it
running across reboots, manage it with a process manager (e.g. pm2,
launchd, or systemd).
run_bash(command: str, cwd?: str, timeout?: int) → text with exit code, stdout,
stderr.
command — the shell command, run via bash -c.cwd — working directory (defaults to where the server started).timeout — seconds before the command is killed (capped by BASH_MCP_MAX_TIMEOUT).| Variable | Default | Meaning |
|---|---|---|
BASH_MCP_ALLOWED | (unset) | Comma-separated command prefixes to allow, e.g. git,ls,cat,npm. Unset = unrestricted. |
BASH_MCP_CWD | server's cwd | Default working directory for commands. |
BASH_MCP_MAX_TIMEOUT | 300 | Hard ceiling (seconds) on any command's runtime. |
BASH_MCP_TRANSPORT | stdio | stdio or http (same as --transport). |
BASH_MCP_HOST | 127.0.0.1 | Bind host for --transport http. |
BASH_MCP_PORT | 8001 | Bind port for --transport http. |
Example — restrict to a safe set:
{
"mcpServers": {
"bash": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/server.py"],
"env": { "BASH_MCP_ALLOWED": "git,ls,cat,grep,npm,node,python3" }
}
}
}
npx @anthropic-ai/mcpb pack . mcp-bash-server.mcpb
This validates manifest.json and produces the installable bundle. The uv
server type means dependencies are resolved from pyproject.toml at install
time — nothing is vendored, so the same bundle works on macOS, Windows, and
Linux.
MIT — see LICENSE.
wyzd0m /
Local MCP server giving Claude customer support tools — Python, FastMCP, Anthropic ecosystem
H3xabah /
Local Ollama-backed MCP server for Claude Code. Query large files without burning context (~30x token savings)
58/100 health