Model or dataset
xyTom/coding-tools-mcp avatar
xyTom/coding-tools-mcp

coding-tools-mcp has one runtime dependency, nineteen tools, and a compose file that ships a default token

Give any AI agent the ability to code

1,223 stars214 forksPythonApache-2.0

At a glance

What is it?
coding-tools-mcp is a model-neutral MCP server that gives any client file reading, structured multi-file patches, command execution, interactive PTY sessions and git, confined to a single workspace root and gated by permission modes. The safety design is the substance here: nineteen annotated tools, one kernel-level confinement story on Linux, and three ways to get a disposable sandbox. The rough edge is in the container defaults.
Who is it for?
coding-tools-mcp fits a team that wants one tool server instead of six, and that is willing to read the permission model before pointing it at anything.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 17 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • xyTom/coding-tools-mcp1,223 ★ · +176
Star history
Repository2026-09-112026-11-15
xyTom/coding-tools-mcp1k1.2k

176 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The runtime dependency list is one line, and it is a JWT library

The project is an MCP server that executes commands on your behalf, and its declared runtime dependency list is:

code
dependencies = [
  "PyJWT>=2.8",
]

One library, for tokens. Everything else is the standard library, which means there is no web framework, no client SDK and no async runtime in the dependency graph of the thing that runs your build. That is a deliberate position for a tool server: fewer transitive updates, fewer things between a prompt and a shell.

The development extras make the same shape visible. The official MCP SDK is there with a comment explaining why: it is the only client in the test suite the authors did not write, and the dual-era smoke test cannot run without it installed. Alongside it sit mypy, ruff, PyYAML and typing_extensions.

Two other extras exist for features that are not the server. `desktop` pulls PySide6 and psutil for the GUI client, and `image` pulls Pillow. The GUI ships its Qt translation files as package data, both the `.ts` sources and the compiled `.qm`, and the Makefile has the matching `pyside6-lupdate` and `pyside6-lrelease` targets, so the second language is a build step rather than a runtime setting.

Permission modes are the product, and exactly one tool can grant

The page's framing is that safety is the product rather than an afterthought, and the mechanisms are named. There is one workspace root per server. Absolute paths, `..` traversal and symlink escapes are rejected. Permission modes gate network access, shell expansion, inline scripts and destructive commands. On Linux, Landlock adds kernel-level filesystem confinement, which is the one control here that the process cannot talk its way around.

Three modes are described. `safe` is the default, meant for day-to-day agent work, and it allows file tools and vetted commands while network-looking commands, shell expansion, inline scripts and destructive commands all require explicit approval. `trusted` is the middle setting. `dangerous` exists, and it is where the interesting asymmetry sits.

The registry contains nineteen truthfully annotated tools. The default and trusted modes advertise eighteen; dangerous also advertises `request_permissions`, described as the only mode in which that tool can grant anything. So capability to widen your own permissions lives in exactly one tool, and that tool is unreachable in the mode you start in.

The catalog itself is four groups: seven file and search tools including the two file-mutation primitives, five execution tools, five git tools, and two runtime tools that report server information and check the execution environment.

The compose sandbox runs trusted mode with a fallback token

The compose file is the shortest path to a working sandbox, and two of its defaults deserve a look before you use it.

yaml
ports:
  - "127.0.0.1:${CODING_TOOLS_MCP_PORT:-8765}:${CODING_TOOLS_MCP_PORT:-8765}"
environment:
  CODING_TOOLS_MCP_PORT: ${CODING_TOOLS_MCP_PORT:-8765}
  CODING_TOOLS_MCP_AUTH_TOKEN: ${CODING_TOOLS_MCP_AUTH_TOKEN:-dev-token}
  CODING_TOOLS_MCP_PERMISSION_MODE: trusted
volumes:
  - .:/workspace

The permission mode is `trusted`, not the documented default of `safe`. And the auth token falls back to the literal string `dev-token` when the environment variable is unset, which is exactly the kind of default that survives in a compose file for years.

The port publishing is the good part: the host side is bound to `127.0.0.1`, so the published port is not reachable from the network even though the container itself listens on all interfaces, which the image sets through `CODING_TOOLS_MCP_HOST=0.0.0.0`. The image also sets `CODING_TOOLS_MCP_GENERATE_AUTH_TOKEN=1`, so a token would be generated if the compose file did not override the variable with a constant.

The volume is the other thing to check. `.:/workspace` mounts your current directory as the workspace root, which is how the one-root confinement works, and it means the sandbox has your working tree.

Three ways to get a sandbox, one of them a single tool call

The page offers three routes, escalating in how much machinery they involve.

The local one is a container built from the repository's own Dockerfile and run interactively:

bash
docker build -t coding-tools-mcp-sandbox:local .
docker run --rm --init -it -p 8765:8765 -v "$PWD:/workspace" coding-tools-mcp-sandbox:local

That image is a full toolchain image, not a minimal one: it copies Go and Rust toolchains in from their own base stages, installs clang, cmake, gcc, g++, make, maven, ninja, node, npm and a headless JDK, and configures the environment so those toolchains work. The stated purpose is pointing an agent at an unfamiliar pull request and destroying the container afterwards.

The cloud one is a bundled Cloudflare Worker control plane that exposes `start_coding_tools_sandbox` as an MCP tool. One call dispatches a GitHub Actions runner which boots the same Docker sandbox and publishes it behind an authenticated Cloudflare Tunnel, which the page frames as ephemeral compute with no server of your own.

The desktop one is the GUI client, installed with the desktop extra and started as `coding-tools-mcp-desktop`, offering per-workspace profiles, server and tunnel start and stop, credential setup with clipboard helpers and live health checks, in English and 简体中文.

Remote access is loopback plus a tunnel, with two auth schemes

Reaching a workstation from somewhere else is a documented, supported path rather than something you have to invent:

bash
CODING_TOOLS_MCP_AUTH_MODE=bearer ./integrations/tunnels/tunnel.sh cloudflared /path/to/repo

The shape is consistent: bind to loopback, then put an authenticated HTTPS tunnel in front of it. Three tunnel tools are named, cloudflared, ngrok and Microsoft Dev Tunnel, and the client points at `https://<tunnel-host>/mcp`. The page says to point claude.ai from a phone at that URL to drive a home workstation, and that ChatGPT and Grok connect the same way through their connector settings.

Two authentication schemes are built in: bearer tokens, and OAuth 2.1 with PKCE including RFC 7591 dynamic registration, which is what a hosted client needs when it cannot hold a static token.

Read that section as an exposure decision rather than a feature list. A tunnel plus a bearer token is a remote shell on your repository behind a token, and the workspace confinement still applies inside it, which is the mitigation the design offers. Whether the token lives on your laptop or on a hosted client is a different question, and the mode you run in is the one that decides what a stolen token is worth.

Interactive processes are first-class, and the container needs init for them

Four tools exist to keep a long-running process alive across turns. `exec_command` starts a REPL or a debugger under a real pseudo-terminal, `write_stdin` feeds it more input, `read_output` pages long output, and `kill_command` cleans up. The page describes long-running processes as first-class, with deadline watchdogs and bounded buffers.

That design has an operational consequence the compose file documents in a comment. `init: true` is set for PID 1 zombie reaping for `exec_command` child processes, with the note that the server itself handles SIGTERM so `docker compose stop` exits promptly either way.

The environment configuration follows the same explicitness. All runtime configuration flows through `CODING_TOOLS_MCP_*` variables, and the image comment explains one of them: `EXEC_ALLOW_ROOTS` only needs the JDK and Maven configuration directories under `/etc`, because everything under `/usr` is already a built-in read root. The image also ships a shell environment override for the Go and Rust homes, since those were copied in from other stages.

Filesystem tools are separate from the shell tools and behave differently. `apply_patch` and `apply_changes` are the file-mutation primitives, and both are staged, baseline-checked, atomic across files and support rollback, which is a stronger guarantee than writing a file and hoping.

Two protocol eras on two transports, and neither one has sessions

The compatibility story is unusually specific. The server implements the MCP specification revision dated 2026-07-28 in full, advertising `tools` as the only capability, and also serves the handshake era dated 2025-11-25 with 2025-06-18 compatibility. Both eras are served on either transport.

The transport choice is one flag. With `--stdio` the server speaks over standard input and output, which is the default for a desktop client. Drop `--stdio` and it speaks Streamable HTTP on `http://127.0.0.1:8765/mcp`.

The no-sessions statement is the part that will matter to someone writing a client: neither era has sessions, so there is no session identifier to thread through and nothing to resume.

The other client-facing decision is a split between text and data. A tool's `content` is concise agent-facing text, while `structuredContent` carries the complete machine result. That is how the project keeps a context window readable without discarding information: the model reads the summary, code reads the payload, and the two are not the same shape.

One published number, its scope, and a release candidate tagged before its release

The page claims context-window engineering and gives one number for it: serialized tool-result bytes dropped 37 percent release over release on the deterministic dogfood workload, with unchanged task completion.

The qualifiers are the claim. Deterministic workload, serialized bytes, task completion held constant. It is not a claim about latency or success rate, and the repository is honest enough to name where the rest lives: a `BENCHMARK.md` at the root, a `benchmarks/` tree that includes an swebench directory, and a `reports/` directory. The Makefile carries matching targets for latency, real workloads, an agent evaluation with its own validation step, and reference prediction generation for swebench.

The dogfood targets also feed back into testing. There are separate targets for a protocol test, an integration test, an MCP contract test, a dual-era test, a tool golden test, a security test, an end-to-end test, a runtime semantics test, a docs-required test and a schema drift test, plus a compliance runner invoked as a module.

One release detail is worth a note. The visible tags include `v0.3.0rc1` at 03:45 and `v0.3.0` at 04:12 on the same day, so the release candidate was tagged before the final, and the newest tag is v0.5.0 from 2026-09-30. The Makefile derives its release tag from the manifest with `tomllib`, so the version has one source.

Editorial conclusion

coding-tools-mcp fits a team that wants one tool server instead of six, and that is willing to read the permission model before pointing it at anything. Verify five things first: which permission mode you are actually running, because the compose file sets trusted rather than the documented default safe; whether you have replaced the compose auth token, because it falls back to the literal dev-token; whether you need `--stdio` or HTTP, since both protocol eras are served either way; how you read the size claims, because the single published figure is scoped to one deterministic workload and BENCHMARK.md is where the detail lives; and whether untrusted code goes in the container rather than on your checkout. Apache-2.0 licensed, at 0.5.0 with a last push dated 2026-09-30.

Frequently asked questions

What is coding-tools-mcp?

It is a model-neutral coding runtime served over the Model Context Protocol, giving any MCP client file reading and search, structured multi-file patches, command execution, interactive sessions and git. The registry holds nineteen annotated tools, confined to one workspace root per server and gated by permission modes.

How do I run coding-tools-mcp?

`uvx coding-tools-mcp --stdio --workspace /path/to/repo` for a Python toolchain, or the same command with `npx` for Node, since the npm package is a thin launcher that starts the PyPI package through uv or pipx. Drop `--stdio` and it speaks Streamable HTTP on http://127.0.0.1:8765/mcp instead.

Which permission modes does coding-tools-mcp have?

safe, trusted and dangerous. Safe is the default and allows file tools and vetted commands, while network-looking commands, shell expansion, inline scripts and destructive commands require explicit approval. `request_permissions` is advertised only in dangerous mode and is the only tool that can grant anything.

Can I point coding-tools-mcp at untrusted code?

The page describes a containerized sandbox built from the repository's Dockerfile with toolchains and caches preconfigured, started with docker run and a workspace mount, as safe to point at an unfamiliar pull request and destroy afterwards. On Linux, Landlock adds kernel-level filesystem confinement on top.

How does coding-tools-mcp keep tool results small?

Results are summarized, paginated and capped by design. A tool's content field holds concise agent-facing text while structuredContent carries the complete machine result. The published figure is a 37 percent drop in serialized tool-result bytes release over release on the deterministic dogfood workload, with unchanged task completion.

What does the coding-tools-mcp desktop client need?

Install the desktop extra with `python -m pip install "coding-tools-mcp[desktop]"`, which pulls PySide6 and psutil, then run `coding-tools-mcp-desktop`. It offers per-workspace profiles, server and tunnel start and stop, credential setup with clipboard helpers and live health checks, in English and 简体中文.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. xyTom/coding-tools-mcp on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/xytom-coding-tools-mcp.svg)](https://hysenlabs.com/projects/xytom-coding-tools-mcp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/xytom-coding-tools-mcp.svg)](https://hysenlabs.com/projects/xytom-coding-tools-mcp)

Was this useful?