Local MCP Toolbox

Secure, local-first visibility for AI-assisted development—without unrestricted machine access.

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

What This Is

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.

Related MCP server: AI Knowledge Center MCP

What You Get

For parameters, output schemas, and every individual guardrail, see the full tool catalog.

Quick Start

Requirements

• 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.

Windows (PowerShell)

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.yml

macOS / Linux

git 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.yml

doctor 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.

Security by Design

The security model is the product boundary, not a feature bolted on afterward.

Read the security model, threat model, and the security-focused architecture decisions for the complete rationale.

How It Works

1. An MCP client requests one registered tool.

2. The toolbox validates typed inputs and bounded parameters.

3. Permissions, approved roots, and integration allowlists are checked.

4. A narrow read-only operation collects the permitted data.

5. Results are redacted and bounded before they cross the MCP boundary.

6. Sanitized request metadata is recorded in the audit log.

7. The client receives a safe structured result or error.

Connect Your AI Client

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.

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.

See It Safely

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.

Architecture

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.

Repository Structure

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

Documentation

Project Status

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.

Contributing and Security

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.

License

MIT. Use it, adapt it, and build a safer local AI workflow with it.

Built with

Python · Model Context Protocol · MCP Python SDK · Pydantic · Typer · Docker