unified-mcp-server
Provides tools for working with Git repositories, including status, initialization, cloning, staging, committing, pushing, pulling, viewing logs, branch management, checkout, diffs, and remote configuration.
Provides tools for managing tmux sessions, including listing sessions and executing commands in tmux panes.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
unified-mcp-server
A self-contained MCP server with file editing and shell execution in one process, one endpoint and one config file. It has 58 tools:
Family | Tools |
Files | read/write/create/copy/move/delete, search & replace, |
Git | status, init, clone, add, commit, push, pull, log, branch, checkout, diff, remote |
Code analysis | tree-sitter |
Linting |
|
Remote |
|
Project |
|
Shell |
|
The code started as two separate servers, mcp-file-edit and shell-mcp-server. It is copied into this package and maintained here; neither project is a dependency.
New here? See docs/USAGE.md for recommended setup, how to run and approve shell commands, keeping secrets away from the model, and upgrading/restarting safely.
Install
One line installs uv (which fetches Python 3.12
if needed) and then the unified-mcp-server command. Git is not required.
Ubuntu / Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh && ~/.local/bin/uv tool install --python 3.12 "unified-mcp-server @ https://github.com/waxz/unified-mcp-server/archive/refs/heads/main.zip"Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"; & "$env:USERPROFILE\.local\bin\uv.exe" tool install --python 3.12 "unified-mcp-server @ https://github.com/waxz/unified-mcp-server/archive/refs/heads/main.zip"The command is installed in ~/.local/bin (%USERPROFILE%\.local\bin on
Windows). If unified-mcp-server isn't found afterwards, open a new terminal or
run uv tool update-shell.
Update (reinstalls from main, then restarts your running HTTP servers in
place: same process, terminal and arguments, new code):
unified-mcp-server --update--update <branch|tag|commit> installs another version, --no-restart only
reinstalls, --version prints the installed version. You can also restart a
running server in place with kill -HUP <pid>. Remove with
uv tool uninstall unified-mcp-server.
On Windows the shell tools run commands through PowerShell (bash maps to
powershell.exe) and the tmux tools are unavailable. CI runs on Ubuntu only.
From a checkout, for development:
uv venv && uv pip install -e ".[dev]"Related MCP server: Coding Tools MCP
Run
stdio (Claude Desktop, Claude Code):
unified-mcp-server -w /path/to/projectclaude mcp add unified -- unified-mcp-server -w /path/to/projectHTTP:
unified-mcp-server -c config.toml -t http -H 127.0.0.1 -P 8000 -p /mcpCLI
Flag | Meaning |
| TOML config. Optional (see below) |
| write a commented config template to PATH (default |
|
|
| HTTP bind settings |
| project directory |
| allowed root directories |
| shell mapping for shell tools (repeatable) |
| prefix tools with |
| disable one family |
| API key for HTTP clients (repeatable; replaces |
| shell command timeout ( |
| shell safety mode ( |
| base URL for patch-preview links ( |
| server runs in a container; run commands directly ( |
| refuse untrusted commands instead of asking you ( |
| files/folders the file tools must never touch; the loaded config file is always protected |
| largest per-call |
| how long an approval request stays open ( |
| how long one tool call waits before returning "pending" ( |
| fixed approvals-dashboard token so its link is stable across restarts ( |
| how untrusted commands are sandboxed: |
| whether a sandboxed command has network ( |
| reinstall from GitHub (default |
| print the installed version |
| let |
Precedence: installed default config → your config file → CLI flags. Environment variables are not read.
A config file is optional. Which one is used:
-c FILEthat exists: that file.-c FILEthat doesn't exist: a warning names the missing file, and the installed default config is used.no
-c:./config.tomlif it exists, otherwise the installed default config.
So a quick HTTP server with a key needs no file at all:
unified-mcp-server -t http -H 127.0.0.1 -P 8000 -p /mcp --api-key change-meArguments are visible to other users on the same machine (for example in
ps), so on shared machines put API_KEYS in a config file instead of using
--api-key. Trusted shell commands can only be defined in a config file.
Configuration
Generate a starting config with every option documented:
unified-mcp-server --init-config # writes ./config.toml
unified-mcp-server -c config.toml -t httpThe template fills in a freshly generated API key, so the file is created
readable by you only (mode 600). It won't overwrite an existing file unless
you pass --force. --init-config - prints the template instead.
Config files written for either original project use the same format and load as they are, as long as the directories they name exist on this machine. Keys this server doesn't know are logged and ignored.
Project directory.
[CONFIG.<os>] work_dir/-wsets the root for file tools. Unless[DOCKER_CONFIG.<os>] host_rootis set, shell commands withcwd="."run there too, and followset_project_directory. Allowed roots are shared the same way.Auth.
API_KEYS = "k1,k2"protects every tool call over HTTP. SendAuthorization: Bearer <key>orx-api-key: <key>. Keys are compared in constant time and never echoed back. stdio has no headers, so keys are ignored there.
Shell execution model
TRUSTED_COMMANDSrun directly on the host, by name:execute_command(command="t_test", cwd=".").Any other command, when no sandbox is configured, needs your approval (
APPROVE_UNTRUSTED = true, the default). Answer wherever is handiest:Approvals dashboard (HTTP): the server prints its link once at startup. Keep the tab open: it lists every waiting request, updates by itself, shows the count in the tab title, and lets you revoke commands you allowed earlier. The link changes on every restart.
Your MCP client's prompt, if it supports MCP elicitation: Submit allows the command once (tick the checkbox to allow it until restart), Decline denies it. The client draws those buttons; the server only adds the checkbox.
A per-request link printed in the server log with each request.
Answers: Allow once, Allow until restart (the same command, shell and working directory then run without asking until the server restarts), or Deny. Nothing is written to
config.toml.A request stays open for
APPROVAL_TIMEOUTseconds (default 600). A tool call waits up toAPPROVAL_WAITseconds (default 25) for your answer; if you haven't answered yet it returns "approval pending" without running anything, and the model calls again with the same arguments once you have. While your client is showing its own prompt, the call waits for that answer instead.Links carry random tokens and appear only in the server's log, never in what the model sees, so the model can't approve its own requests. Keep that log outside the folders the file tools can read. The working directory must still be inside the allowed roots.
--no-approvalrefuses untrusted commands instead. Over stdio with a client that can't show prompts there is no way to approve, so the command is refused; useTRUSTED_COMMANDSthere.With a sandbox configured (
SANDBOX), untrusted commands run in it instead of asking for approval. The server builds the sandbox itself, and there is one filesystem path space: the sandbox binds the project directory at the same path, so a command sees the same paths inside and out (no host/container mapping).SANDBOX = "bubblewrap"(Linux; needs thebubblewrappackage): the whole filesystem read-only except the project directory, a private/tmp, and its own user/pid/ipc/net namespaces. No Docker, no daemon, no helper script.SANDBOX = "docker": a throwawaydocker run --rmcontainer with only the project directory mounted, as the current user, optionally withDOCKER_SANDBOX_CPUS/DOCKER_SANDBOX_MEMORYcaps.SANDBOX_NETWORK = "none"cuts network inside the sandbox (default"allow"). The command is passed tobwrap/dockeras a single argument, never interpolated into a shell, so there is no outer-shell injection. If the chosen sandbox's tool is missing the server refuses to start (fail closed). Unset,SANDBOXis"none"(approval).
Set
IS_IN_DOCKER = truewhen the server itself runs inside a container: every command then runs directly in it.On Windows there is no built-in sandbox (
bubblewrapanddockerneed a Linux host), so an untrusted command is gated by the same approve/decline flow as on Linux: it runs only after you allow it (in your client's prompt or on the approvals dashboard), and is refused if approvals are off (--no-approval). Add it toTRUSTED_COMMANDSto skip the prompt. SettingSANDBOX = "docker"on Windows is rejected at startup so a command can't slip past both the sandbox and the approval gate.SAFETY_MODE = "strict"forcesbashfor untrusted commands.tmux:
tmux_executecreates host sessions namednative_mcp_<name>, and the other tmux tools act on those directly. Any other session name is treated as a sandbox session, so without a sandbox configured those calls return an error. Your own tmux sessions aren't reachable.tmux_send_keyscan't type into host (native_mcp_*) sessions unlessALLOW_HOST_TMUX_INPUT = true(or--allow-host-tmux-input). Typing into a host shell runs any command, which would bypassTRUSTED_COMMANDS, so it is off by default.
Changes from the original projects
Structure
files/holds the file tools andshell/the shell tools. Code both projects duplicated lives once incommon/.Both tool families share one
Settingsmodel, one loader and one FastMCP app. Tools are registered directly; there is no proxying or mounting.Settings is a plain pydantic model, not
BaseSettings, so the systemPATH/HOSTenvironment variables can't leak into the server'sPATH/HOSTfields.The unused
fuzzy_patch.py(it needed an uninstalled library) and a debugging tmux helper that printed to stdout were not copied.
Bugs fixed
tmux_executesentC-cto a new pane before its shell had started, killing the shell and the tmux server. This failed every time on GitHub runners. The bootstrap now waits for the pane's prompt and the reset no longer sendsC-c. (shell/tmux_commands.py)tmux_get_output,tmux_send_keysandtmux_kill_sessioncrashed (cwd=None) or failed with "Directory not allowed" on any session not namednative_mcp_*when no sandbox was configured. They now return an error that explains why. (shell/tool_handlers.py)tmux_list_sessioncrashed withcwd=Nonewhen no sandbox work dir was configured, and raised when no tmux server was running. It now checks the sandbox only when one exists, returns[]with no server, and drops blank names. (shell/tool_handlers.py)The Windows shell adapter crashed (
'NoneType' has no attribute 'replace') when no sandbox root was configured, and in relaxed mode ran an untrustedcmd/powershellcommand straight on the host with no sandbox. It now guards the crash and refuses those untrusted commands. The untrusted sandbox is also a real, server-built bubblewrap/docker jail rather than an undefined externaldrun, and a misconfigured sandbox fails the server at startup instead of running commands unsandboxed. (shell/sandbox.py, shell/platform_adapters/windows.py)The inherited shell sandbox had two filesystem path spaces -- a host space and a separate docker-container space (
DOCKER_SANDBOX_WORKDIR,ALLOWED_DIRECTORIES_DOCKER, host->container cwd mapping,drunoverride env) -- so a command ran partly on host paths and partly on mapped container paths. That mixture (and its mapping bugs) is removed: there is now one host path space, sandboxes bind the project dir at the same path, and a config that still sets the oldwork_dir/drunfails at startup with a migration message. (shell/execution_policy.py, shell/sandbox.py)--updateon Windows no longer fails with "Access is denied". The runningunified-mcp-server.exe/python.exelive inside the uv tool env thatuv tool install --reinstallwipes, and Windows won't delete in-use files (os error 5removing...\Scripts). When the updater is running from inside the env it's replacing, the reinstall is now handed to a detached step that waits for this process to exit (unlocking the files) and then installs; restart the server afterwards. (update.py)CI security-guards gate. A dedicated suite (run as its own CI step) asserts the server refuses dangerous tool calls and that the side effect never happens: file access outside the working directory (
..traversal, an absolute path, a symlink pointing out of the project, a protected file) and dangerous/untrusted shell commands (refused with no sandbox and no approval, and never executed). (tests/test_security_guards.py, .github/workflows/ci.yml)apply_patchpreview/confirm no longer corrupts file content. The dry-run diff was built fromsplitlines(keepends=True)joined with"\n"(withlineterm=""), doubling every newline -- so the shown diff, and the content the confirm/apply path rebuilt from that diff, gained a blank line after every line. Worse, rebuilding from a unified diff dropped every line outside a hunk, so confirming a patch on any non-trivial file truncated it. The dry-run now carries the exact full post-patch content, and the preview writes that verbatim on confirm (never reconstructs it from the diff); the diff itself is generated correctly. (files/file_patch_tools.py)get_file_info().absolute_pathis now absolute. It was built relative to the project dir, so it equalledrelative_pathand contradicted its name. (files/utils.py)patch_fileno longer leaves an orphan.backup_*when no patch matched: the file isn't modified, so the pre-emptive backup is removed. (files/file_tools.py)read_filewith an out-of-range line window now returnstotal_lines, the resolved range, and awarning, instead of silently looking like an empty file. (files/file_tools.py)cmd output no longer gets a stray trailing quote. A
shell="cmd"command was invoked ascmd.exe /c "<command>", whose/cquote heuristic leaks a trailing quote on a nested/quoted command line (e.g.cmd /c echo hiprintedhi"). cmd is now invoked ascmd.exe /d /s /c "<command>":/sstrips exactly the outer quote pair and runs the rest verbatim, avoiding the heuristic. (shell/platform_adapters/windows.py)Windows commands no longer break with "
&&is not a valid statement separator". The shell adapter prepended( cd '<cwd>' && <command> )-- bash syntax -- to every command, but on Windowsshell="bash"maps to PowerShell (and strict mode coerced untrusted commands to it), where&&isn't a statement separator, soexecute_command/tmux_executefailed even withcwd/shellgiven. The working directory is set by the spawn, so the adapter no longer chainscdat all: each shell (cmd / PowerShell / pwsh / wsl / real bash, dispatched by the actual program) just receives the command. Strict mode also no longer forcesbashon Windows, so an explicitshell="cmd"is honored end-to-end. (shell/platform_adapters/windows.py, shell/approvals.py)Windows now uses the same approve/decline gate as Linux. An untrusted command on Windows (no OS sandbox) goes through the approval flow and runs once allowed -- it is no longer dead-refused with "run on a Linux host". The fail-closed refusal (approvals off, no sandbox) is now one shared message on both OSes.
SANDBOX = "docker"on a Windows host is rejected at startup rather than silently skipping approval and then failing to run (it can't bind host paths 1:1 into a Linux container), so an untrusted command can never slip past both gates. (shell/executor.py, shell/sandbox.py, shell/platform_adapters/windows.py)read_file,patch_fileandapply_patchmisread text files with an unrecognised extension (.mjs,.cjs,.mts,.lock, ...) as binary, because the fallback trusted the host mime database and treated everyapplication/*type as binary. File type is now decided from the bytes (NUL byte / UTF-8), which doesn't vary by machine. (files/utils.py)Failed commands came back as a Python list repr (
['…', '[exit code: 1]']) with the timeout note twice; they are now plain text. A client disconnect raised a validation error instead of returning. (common/mcp_types_utils.py, shell/tool_handlers.py)remove_directoryand recursivedelete_fileusedshutil.rmtree(onexc=...), which needs Python 3.12. They now work on 3.11. (files/file_operations.py)Code analysis skipped every
async def(novisit_AsyncFunctionDef). (files/code_analyzer.py)A timed-out command crashed while formatting its result (
configwas never imported). (common/mcp_types_utils.py)Auth: Bearer tokens never worked, because the
Authorizationheader was stripped. A failed check also echoed the key and all request headers back to the caller. (server.py)fastmcp 4.x removed
fastmcp.server.tasks; the dependency is pinned<4.
Tests & CI
uv pip install -e ".[dev]"
pytest -qtests/test_tools.pycalls every tool family through a real MCP client. It also checks the exact set of 58 registered tools.tests/test_unified.pycovers config, namespacing, the shared project directory, the installed console script over stdio, and API-key auth over real HTTP.tests/test_fixes.pyholds a regression test for each fixed bug, including a reproduction of the tmux race using a shell that is slow to start.
CI (.github/workflows/ci.yml) runs the suite on Ubuntu with
Python 3.11, 3.12 and 3.13.
License
The code comes from an MIT-licensed project (mcp-file-edit) and an
Apache-2.0-licensed project (shell-mcp-server), so the package is
MIT AND Apache-2.0. See NOTICE, LICENSE-MIT and LICENSE-APACHE. Each
copied file says which project it came from.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
Create, edit, preview, and deploy full-stack web apps to a live URL from any MCP client.
Notes, files, GitHub, and Drive through one MCP connection.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables reading, writing, editing, searching, running commands, transferring files, and using git on a remote Linux server over SSH via MCP tools.223AGPL 3.0
- AlicenseBqualityDmaintenanceEnables any MCP client to read, search, patch, and execute commands in a codebase, including interactive sessions and git operations, with permission modes and safety boundaries.18Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to treat a remote Linux host over SSH as a local working tree, exposing editor-semantics operations, background job management, artifact transfer, and guard hooks through MCP.1MIT
- AlicenseDqualityCmaintenanceEnables controlled local developer operations including file and process management, shell execution, SSH, WSL, Docker, Git, browser and desktop automation, media processing, and asynchronous jobs through MCP.146MIT