Skip to main content
Glama
unified-mcp-server

unified-mcp-server

by waxz

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, patch_file, apply_patch with preview → confirm → apply (plus a browser review page over HTTP), get_file_info

Git

status, init, clone, add, commit, push, pull, log, branch, checkout, diff, remote

Code analysis

tree-sitter list_functions, get_function_at_line, get_code_structure, search_functions

Linting

detect_linters, run_linter, lint_file, run_type_checker, type_check_file, format_file

Remote

ssh_upload, ssh_download, ssh_sync, SSH project directories

Project

set_project_directory, get_project_directory

Shell

execute_command (streamed output), list_trusted_commands, process list/terminate, tmux sessions

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/project
claude mcp add unified -- unified-mcp-server -w /path/to/project

HTTP:

unified-mcp-server -c config.toml -t http -H 127.0.0.1 -P 8000 -p /mcp

CLI

Flag

Meaning

-c/--config

TOML config. Optional (see below)

--init-config [PATH]

write a commented config template to PATH (default config.toml, - prints it) and exit; --force overwrites

-t/--transport

stdio or http

-H/--host, -P/--port, -p/--path

HTTP bind settings

-w/--workdir

project directory

-d/--directories

allowed root directories

--shell NAME PATH

shell mapping for shell tools (repeatable)

--namespaced

prefix tools with fs_ / shell_

--no-files / --no-shell

disable one family

--api-key KEY

API key for HTTP clients (repeatable; replaces API_KEYS)

--command-timeout SECONDS

shell command timeout (COMMAND_TIMEOUT)

--safety-mode strict|relax

shell safety mode (SAFETY_MODE)

--public-url URL

base URL for patch-preview links (PUBLIC_URL)

--in-docker

server runs in a container; run commands directly (IS_IN_DOCKER)

--no-approval

refuse untrusted commands instead of asking you (APPROVE_UNTRUSTED = false)

PROTECTED_PATHS (config only)

files/folders the file tools must never touch; the loaded config file is always protected

COMMAND_TIMEOUT_MAX (config only)

largest per-call timeout for execute_command (default 600)

--approval-timeout SECONDS

how long an approval request stays open (APPROVAL_TIMEOUT, default 600)

--approval-wait SECONDS

how long one tool call waits before returning "pending" (APPROVAL_WAIT, default 25)

--dashboard-token TOKEN

fixed approvals-dashboard token so its link is stable across restarts (APPROVALS_DASHBOARD_TOKEN)

--sandbox MODE

how untrusted commands are sandboxed: none/bubblewrap/docker (SANDBOX)

--sandbox-network allow|none

whether a sandboxed command has network (SANDBOX_NETWORK)

--update [REF]

reinstall from GitHub (default main), restart running HTTP servers in place, exit; --no-restart to skip the restart

--version

print the installed version

--allow-host-tmux-input

let tmux_send_keys type into host sessions (ALLOW_HOST_TMUX_INPUT; runs arbitrary commands)

Precedence: installed default config → your config file → CLI flags. Environment variables are not read.

A config file is optional. Which one is used:

  • -c FILE that exists: that file.

  • -c FILE that doesn't exist: a warning names the missing file, and the installed default config is used.

  • no -c: ./config.toml if 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-me

Arguments 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 http

The 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 / -w sets the root for file tools. Unless [DOCKER_CONFIG.<os>] host_root is set, shell commands with cwd="." run there too, and follow set_project_directory. Allowed roots are shared the same way.

  • Auth. API_KEYS = "k1,k2" protects every tool call over HTTP. Send Authorization: Bearer <key> or x-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_COMMANDS run 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_TIMEOUT seconds (default 600). A tool call waits up to APPROVAL_WAIT seconds (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-approval refuses untrusted commands instead. Over stdio with a client that can't show prompts there is no way to approve, so the command is refused; use TRUSTED_COMMANDS there.

  • 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 the bubblewrap package): 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 throwaway docker run --rm container with only the project directory mounted, as the current user, optionally with DOCKER_SANDBOX_CPUS / DOCKER_SANDBOX_MEMORY caps.

    • SANDBOX_NETWORK = "none" cuts network inside the sandbox (default "allow"). The command is passed to bwrap/docker as 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, SANDBOX is "none" (approval).

  • Set IS_IN_DOCKER = true when the server itself runs inside a container: every command then runs directly in it.

  • On Windows there is no built-in sandbox (bubblewrap and docker need 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 to TRUSTED_COMMANDS to skip the prompt. Setting SANDBOX = "docker" on Windows is rejected at startup so a command can't slip past both the sandbox and the approval gate.

  • SAFETY_MODE = "strict" forces bash for untrusted commands.

  • tmux: tmux_execute creates host sessions named native_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_keys can't type into host (native_mcp_*) sessions unless ALLOW_HOST_TMUX_INPUT = true (or --allow-host-tmux-input). Typing into a host shell runs any command, which would bypass TRUSTED_COMMANDS, so it is off by default.

Changes from the original projects

Structure

  • files/ holds the file tools and shell/ the shell tools. Code both projects duplicated lives once in common/.

  • Both tool families share one Settings model, 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 system PATH/HOST environment variables can't leak into the server's PATH/HOST fields.

  • 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_execute sent C-c to 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 sends C-c. (shell/tmux_commands.py)

  • tmux_get_output, tmux_send_keys and tmux_kill_session crashed (cwd=None) or failed with "Directory not allowed" on any session not named native_mcp_* when no sandbox was configured. They now return an error that explains why. (shell/tool_handlers.py)

  • tmux_list_session crashed with cwd=None when 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 untrusted cmd/powershell command 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 external drun, 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, drun override 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 old work_dir/drun fails at startup with a migration message. (shell/execution_policy.py, shell/sandbox.py)

  • --update on Windows no longer fails with "Access is denied". The running unified-mcp-server.exe / python.exe live inside the uv tool env that uv tool install --reinstall wipes, and Windows won't delete in-use files (os error 5 removing ...\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_patch preview/confirm no longer corrupts file content. The dry-run diff was built from splitlines(keepends=True) joined with "\n" (with lineterm=""), 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_path is now absolute. It was built relative to the project dir, so it equalled relative_path and contradicted its name. (files/utils.py)

  • patch_file no 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_file with an out-of-range line window now returns total_lines, the resolved range, and a warning, 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 as cmd.exe /c "<command>", whose /c quote heuristic leaks a trailing quote on a nested/quoted command line (e.g. cmd /c echo hi printed hi"). cmd is now invoked as cmd.exe /d /s /c "<command>": /s strips 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 Windows shell="bash" maps to PowerShell (and strict mode coerced untrusted commands to it), where && isn't a statement separator, so execute_command/tmux_execute failed even with cwd/shell given. The working directory is set by the spawn, so the adapter no longer chains cd at all: each shell (cmd / PowerShell / pwsh / wsl / real bash, dispatched by the actual program) just receives the command. Strict mode also no longer forces bash on Windows, so an explicit shell="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_file and apply_patch misread text files with an unrecognised extension (.mjs, .cjs, .mts, .lock, ...) as binary, because the fallback trusted the host mime database and treated every application/* 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_directory and recursive delete_file used shutil.rmtree(onexc=...), which needs Python 3.12. They now work on 3.11. (files/file_operations.py)

  • Code analysis skipped every async def (no visit_AsyncFunctionDef). (files/code_analyzer.py)

  • A timed-out command crashed while formatting its result (config was never imported). (common/mcp_types_utils.py)

  • Auth: Bearer tokens never worked, because the Authorization header 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 -q
  • tests/test_tools.py calls every tool family through a real MCP client. It also checks the exact set of 58 registered tools.

  • tests/test_unified.py covers config, namespacing, the shared project directory, the installed console script over stdio, and API-key auth over real HTTP.

  • tests/test_fixes.py holds 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables reading, writing, editing, searching, running commands, transferring files, and using git on a remote Linux server over SSH via MCP tools.
      22
      3
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      D
      quality
      C
      maintenance
      Enables 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.
      146
      MIT