A read-only Model Context Protocol server that gives AI clients narrowly scoped, auditable access to developer-environment signals: system metadata, approved files, repositories, logs, containers, scanners, and incident evidence.
Current release: v1.0.0 — stable read-only core
Quick Start · Tools · Security · How It Works · Connect a Client · Architecture · Demo · Roadmap · Contributing
AI assistants are useful when they can inspect the environment around a problem. A generic shell tool or unrestricted Docker socket, however, turns that useful visibility into a high-privilege control plane.
Local MCP Toolbox takes a different path: it exposes a small set of typed, read-only MCP tools behind explicit policy checks. An operator chooses the approved roots and integrations; the server validates the request, collects only bounded data, redacts sensitive material, records sanitized audit metadata, and returns structured evidence to the client.
The result is a practical way to connect MCP-capable clients to local developer signals without treating client access as host access.
| Capability | What it does | Security boundary |
|---|---|---|
| System | Safe host metadata and developer-tool availability | No environment variables, usernames, process data, or executable paths |
| Filesystem | Approved-root listing, metadata, and text inspection | Canonical containment, sensitive-path blocklist, extension allowlist, bounded reads |
| Git | Repository status, branch, commits, and diff summaries | Explicit repository allowlist; fixed, non-interactive Git commands |
| Docker | Opt-in container metadata, health, and bounded logs | Official SDK only; no lifecycle, exec, mount, environment, or command access |
| Logs | Tails, literal search, and deterministic error grouping | Dedicated approved roots, output limits, and central redaction |
| Security | Bandit availability and normalized scan findings | Fixed scanner invocation; no user-controlled command arguments or fixes |
| Infrastructure | Project-type detection and top-level configuration inventory | Separate approved roots; no recursive content inspection |
| Incidents | Timestamped evidence and deterministic summaries | Read-only, bounded observations—never root-cause claims |
| Audit | Sanitized JSONL accountability trail | Shape-only request summaries, retention, and size limits |
For parameters, output schemas, and every individual guardrail, see the full tool catalog.
- Python 3.12 or later
- An MCP-capable client for connection after the server is validated
The default restricted profile is intentionally safe: it starts with no approved filesystem roots and no optional integrations.
git clone https://github.com/chriswayneh/local-mcp-toolbox.git
Set-Location local-mcp-toolbox
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev,docker]"
.\.venv\Scripts\local-mcp-toolbox doctor --config config\restricted.yml
.\.venv\Scripts\local-mcp-toolbox serve --config config\restricted.ymlgit clone https://github.com/chriswayneh/local-mcp-toolbox.git
cd local-mcp-toolbox
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev,docker]"
.venv/bin/local-mcp-toolbox doctor --config config/restricted.yml
.venv/bin/local-mcp-toolbox serve --config config/restricted.ymldoctor is a non-mutating preflight check. The server uses stdio; reserve standard output for MCP traffic and keep diagnostics on standard error. For a guided setup and policy configuration, see getting started.
The security model is the product boundary, not a feature bolted on afterward.
| Control | Protection |
|---|---|
| Deny by default | The restrictive profile has no approved filesystem roots or integrations. |
| Approved roots | Canonical containment blocks arbitrary filesystem access and escape paths. |
| Read-only surface | No generic shell, mutation, commit, lifecycle, or remote-execution tool is registered. |
| Fixed subprocesses | External binaries use fixed argument templates, shell=False, scrubbed environments, timeouts, and output caps. |
| Central redaction | PEM blocks, credentials, cookies, authorization headers, connection strings, and optional privacy identifiers are redacted before output. |
| Output bounds | File reads, collections, subprocess output, and responses are size-limited. |
| Sanitized audit | Requests record safe metadata, actual outcomes, and redaction counts—not raw secrets or tool output. |
| Explicit integrations | Git, Docker, logs, scanners, infrastructure, and incident tools must be configured intentionally. |
| Untrusted evidence | Retrieved files, logs, commit messages, and metadata are data—not instructions. |
Read the security model, threat model, and the security-focused architecture decisions for the complete rationale.
- An MCP client requests one registered tool.
- The toolbox validates typed inputs and bounded parameters.
- Permissions, approved roots, and integration allowlists are checked.
- A narrow read-only operation collects the permitted data.
- Results are redacted and bounded before they cross the MCP boundary.
- Sanitized request metadata is recorded in the audit log.
- The client receives a safe structured result or error.
The repository includes maintained stdio configuration templates for supported clients. Adding a client entry lets the client start the process—it does not grant the server broader permissions.
| Client | Copy-ready template |
|---|---|
| Codex | examples/codex/config.toml |
| Claude Desktop | examples/claude-desktop/claude_desktop_config.json |
| Claude Code | examples/claude-code/.mcp.json |
| Visual Studio Code | examples/vscode/mcp.json |
Replace the intentionally unresolved paths, then configure the smallest local policy that serves the task. See client configuration for exact installation notes and the important separation between client startup and server authorization.
This project is designed for evidence, not a dashboard. The synthetic demo walkthrough provides a reproducible way to see the policy boundary in action without real credentials, repositories, production logs, or a host Docker socket.
It demonstrates a safe inspection sequence:
toolbox_server_status → verify the server and active profile
logs_tail_file → view redacted synthetic log evidence
logs_error_summary → group observed errors without causal claims
infra_detect_project_types → inspect demo project metadata
docker_unhealthy_containers → observe an intentionally unhealthy demo service
The demo’s fabricated token is redacted, disabled integrations return a structured denial, and its audit trail contains sanitized metadata only. Follow the walkthrough to run it locally.
flowchart LR
Client["MCP client"] --> Transport["stdio transport"]
subgraph Boundary["Local policy enforcement boundary"]
Registry["MCP server / tool registry"] --> Permission{"Permission check"}
Permission -->|Denied| Error["Safe structured error"]
Permission -->|Allowed| Tool["Narrow read-only tool"]
Tool --> Guard["Redaction + output limits"]
end
Transport --> Registry
Guard --> Client
Registry -. "sanitized metadata" .-> Audit["JSONL audit log"]
Tool --> Integration["Explicitly approved local integrations"]
classDef boundary fill:#EAF3FF,stroke:#4A78A8,color:#102A43
classDef control fill:#E9F7EF,stroke:#2E7D32,color:#173E22
classDef denial fill:#FDECEC,stroke:#C62828,color:#5C1111
class Registry,Tool,Guard boundary
class Permission,Audit,Integration control
class Error denial
All retrieved content remains untrusted data. The full component model and trust-boundary discussion live in architecture.
src/mcp_toolbox/ MCP server, tool modules, permissions, redaction, audit, config, and CLI
tests/ Unit, integration, and security regression tests
config/ Restricted, standard, and container policy profiles
docs/ Architecture, threat model, operating guides, ADRs, and tool reference
examples/ MCP client configuration templates
demo/ Synthetic services, logs, and intentionally insecure test fixtures
.github/ CI, security, documentation, release, Dependabot, and contribution templates
| Document | Purpose |
|---|---|
| Architecture | System design, components, and data flow |
| Security Model | Controls and trust boundaries |
| Threat Model | Threat analysis and mitigations |
| Permissions | Authorization sequence and profile behavior |
| Tool Catalog | Inputs, outputs, and module-level guardrails |
| Client Configuration | Codex, Claude, and VS Code setup |
| Docker | Hardened container profiles and socket-proxy guidance |
| Demo Walkthrough | Synthetic end-to-end policy demonstration |
| CI and Release | Quality, security, docs, package, and release controls |
| Roadmap | Planned Version 1.5+ scope |
Version 1.0.0 delivers the secure read-only core: MCP stdio transport, typed tools, policy enforcement, centralized redaction, structured errors, sanitized auditing, Docker packaging, a synthetic demo, and CI/release controls.
GitHub, Kubernetes, local LLM, HTTP transport, dashboards, and all write operations are intentionally deferred. See the roadmap and changelog for release history and future scope.
Contributions are welcome when they preserve the project’s least-privilege model. Start with CONTRIBUTING.md, use the repository templates for bugs and feature proposals, and report vulnerabilities through the process in SECURITY.md.
MIT. Use it, adapt it, and build a safer local AI workflow with it.
Python · Model Context Protocol · MCP Python SDK · Pydantic · Typer · Docker
Built to explore a simple idea: AI tooling can be useful without being all-powerful.
If this project proves useful, a ⭐ is appreciated.