Local MCP Toolbox

Read-only inspection with explicit access controls.

A local Model Context Protocol server for checking files, Git changes, application logs, container health, and Python environments. You choose what it can inspect. Every request is authorized, sensitive output is redacted, results are bounded, and activity is audited.

Current release: v1.6.1. It makes Git tool output safer (invisible and control characters are escaped, and the branch name is reported in a new repository) and closes two Windows file-reading races. v1.6.0 added a static auditor for agent instruction files, skills, prompts, and MCP configs. See the changelog and the v1.5 release contract.

Local MCP Toolbox supports development, security review, and troubleshooting workflows that need evidence without broad machine authority.

Use it to review changes in an approved repository, investigate recurring log errors, or check an unhealthy container. Each integration requires explicit configuration. Returned evidence helps you investigate; it does not establish a root cause by itself.

The exposed tools cannot edit your files, commit code, restart containers, execute arbitrary commands, or mutate remote systems. The server writes only its own security audit records. It runs locally and connects to an MCP client; there is no separate dashboard.

Demo

The GIF replays real v1.6.1 output against the synthetic demo/agent-configs fixtures. Run the demo.

Related MCP server: AI Knowledge Center MCP

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

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

doctor checks configuration and prerequisites without changing them. Its JSON status is ready only when every check passed or was skipped; a warning makes it attention, and the command still exits 0. Review any reported issues, then connect your client using the supplied template. The client starts the server when needed.

For a manual startup check, run local-mcp-toolbox serve --config config/restricted.yml using the executable in your virtual environment. It waits for MCP messages and does not open a browser. Press Ctrl+C to stop it before letting your client start its own instance.

The default profile has no approved file roots or optional integrations. Start by asking your client to call toolbox_server_status. Then follow getting started to grant only the access you need. The install above includes development and Docker support; Docker itself is optional and remains disabled until configured.

Try the agent config auditor

You can check agent instruction files and MCP configs right away, with no config file and no server running. The repository ships two small synthetic examples: demo/agent-configs/benign (should come back clean) and demo/agent-configs/risky (full of planted problems).

.venv/bin/local-mcp-toolbox audit-agent-configs demo/agent-configs/benign
.venv/bin/local-mcp-toolbox audit-agent-configs demo/agent-configs/risky

On Windows use .\.venv\Scripts\local-mcp-toolbox instead. The risky example prints one line per finding, for example:

status: findings_detected (files_scanned=2, withheld_files=0, total_findings=14, high=13, medium=1, low=0)
[HIGH] AGENT-MCP-002 (mcp_config_risk) .mcp.json:4 - Cleartext remote MCP server URL
[HIGH] AGENT-EXEC-001 (dangerous_execution) SKILL.md:6 - Piped remote command execution snippet

Useful options:

• --json prints a machine-readable report (findings, counts by severity and category, and scan stats) for scripts and CI.

• --fail-on low|medium|high|none sets the lowest severity that makes the command fail. The default is low, so any finding fails. none always exits 0 when the scan itself worked.

.venv/bin/local-mcp-toolbox audit-agent-configs demo/agent-configs/risky --json --fail-on high

Exit codes, so you can use it as a CI gate:

The auditor only reads files. It never runs them, never starts a shell, and never contacts the network. Every rule ID it can report is listed in the tool catalog.

Features

What You Get

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

Usage

Limits in force

The server enforces the YAML file passed to --config. The shipped default, config/restricted.yml (the same policy values as config/default.yml), approves nothing:

• No filesystem roots. File tools deny every path.

• Docker, Git, GitHub, logs, scanners, infrastructure, incidents, Python environments, and external network are off.

• File reads stop at 240,000 bytes. Directory scans stop at 500 entries. Responses stop at 100 records and 262,144 bytes. Subprocess and GitHub calls time out after 10 seconds.

• Readable extensions are .md, .txt, .json, .yaml, .yml, .toml, .py, and .ts. Blocked names are .env, .env.*, id_rsa, id_ed25519, *.pem, *.key, and credentials*.

• Home-directory paths are redacted. Email addresses and IP addresses are not, unless that policy option is turned on.

• Audit events are capped at 8,192 bytes and segments at 8,388,608 bytes. Closed segments are kept for 30 days. A relative audit.path is resolved from the configuration file's directory, not the process working directory.

• HTTP is disabled. profile: advanced is rejected.

Those are the running defaults, not the schema ceilings. An operator can raise several numbers inside a private profile; the ceilings, and the defaults that apply only after an integration is enabled, are in the security model. Pattern redaction is not a guarantee that every secret is recognized.

Audit Agent Instructions and MCP Configs

Teams often adopt shared instruction files (AGENTS.md, CLAUDE.md, SKILL.md, .cursorrules, .github/copilot-instructions.md) and .mcp.json configurations across repositories. You can audit these files statically from the CLI or in CI before an agent loads them, without starting the MCP server:

.venv/bin/local-mcp-toolbox audit-agent-configs demo/agent-configs/benign
.venv/bin/local-mcp-toolbox audit-agent-configs demo/agent-configs/risky --json --fail-on medium

The auditor checks five deterministic categories (hidden_unicode, prompt_override, dangerous_execution, credential_or_exfil, and mcp_config_risk), redacts secrets in snippets, escapes invisible or bidirectional control characters, and exits with code 0 when clean, 1 when findings meet or exceed --fail-on, and 2 on invalid input or unreadable targets. The same check is available to MCP clients as security_audit_agent_configs when security_scanners is enabled.

Why Audit Agent Configs?

Prompts, agent skills, and MCP server entries are easy to share, so they often move from a blog, a chat thread, or another repository straight into an agent's context with no review. To an agent, though, these plain text and JSON files act like code: they can tell it what to run, what to read, and which servers to trust. Many endpoint security tools are not designed to review the contents of these files, so a risky instruction can go unnoticed until the agent acts on it.

audit-agent-configs gives you a quick local check before you adopt one. Its 18 rules flag:

• Hidden text: bidirectional controls, invisible tag characters, zero-width and control characters, and directives tucked inside HTML comments.

• Instruction overrides: text telling the agent to ignore earlier instructions, hide actions from the user, or skip confirmation and safety checks.

• Risky execution: downloads piped into a shell, decoded payloads that are then run, and network-fetching Python or Node one-liners.

• Credential access and exfiltration: references to .env files, SSH keys, cloud credential files, or metadata endpoints, plus webhook collectors and uploads to outside hosts.

• Untrusted MCP servers: plain-HTTP or other remote endpoints, unpinned packages, shell-wrapped commands, code-injecting environment variables, inline secrets, and malformed configs.

It is pattern based and runs only when you call it; nothing is checked automatically, and a clean result is not proof that a file is safe. To make it routine, run it in CI or a Git pre-commit hook. It takes one target path and recursively scans recognized agent and MCP config filenames (the full list is in the tool catalog). --include <glob> replaces the default filename list, so to check extra files pass --include for every pattern you want scanned, including the defaults:

# CI step or .git/hooks/pre-commit, run from an activated virtual environment
# (or call .venv/bin/local-mcp-toolbox). Fails (exit 1) on any high-severity finding.
# Point it at your own config paths.
# Note: --include <glob> replaces the default filename discovery; it does not add to it.
local-mcp-toolbox audit-agent-configs . --fail-on high

Connect a Client

The repository includes stdio configuration templates for the clients below. Template parsing and the installed server's launch contract are tested; individual desktop application versions are not certified. 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.

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

Architecture

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.

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.

Built with

Languages (GitHub language stats, checked 2026-10-21): Python 98.6%, PowerShell 0.7%, Makefile 0.3%, Dockerfile 0.2%

AI tools:

• Grok Bot (confirmed by Chris, 2026-10-21)

• Cursor cloud agents (confirmed by Chris, 2026-10-21)

• OpenAI Codex (commit co-author trailer)

Commits made with AI help carry a Co-authored-by trailer from now on. See CONTRIBUTING.md.

Roadmap

See ROADMAP.md for planned phases and CHANGELOG.md for released versions.

Project Status

Version 1.5 adds allowlisted GitHub inspection, content-free runtime metrics, a static Python environment auditor, authenticated loopback HTTP, crash-safe audit rotation, and hardened release controls. Kubernetes inspection and generation features were removed after security review because their effective behavior could not satisfy the inspection-only contract.

Version 1.6.1 is the current release. It escapes control and invisible characters in Git tool output, reports the branch name in a repository with no commits, and verifies the real path of files opened on Windows. Version 1.6.0 added the read-only agent config auditor (security_audit_agent_configs and local-mcp-toolbox audit-agent-configs) and tightened secret redaction, while keeping the v1.5 inspection-only contract. Support is limited to the local inspection contract in the acceptance record, not a hosted service, multi-user security boundary, or production availability guarantee. The package classifier Production/Stable means that local contract, not a hosted production service. Versions 2 through 4 are optional proposals, not unfinished release requirements.

Security

See SECURITY.md for supported versions and how to report a vulnerability privately.

Security by Design

The design applies zero-trust principles and least privilege: each tool request is checked against local policy, and integrations receive only the access you explicitly configure. Local execution alone does not authorize access to a path, repository, or optional integration.

The workstation, configured policy, installed dependencies, and any enabled Docker proxy remain trusted components. Read-only tools are not an operating-system sandbox, and the loopback HTTP token is not multi-user identity. These controls do not constitute a complete enterprise zero-trust architecture or security certification. See the verified limitations.

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

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.

Contributing

See CONTRIBUTING.md, including how to credit AI tools in commits.

License

Licensed under the MIT License. Use it, fork it, modify it, or build something of your own. See LICENSE for the terms.

If this project helped you, a star is appreciated.

Acknowledgments

README layout adapted from Best-README-Template by Othneil Drew.