Skip to content

Security Guide

Overview

KiCad MCP can read and modify PCB/schematic project files when write tools are enabled. This guide explains the security model and best practices.

Principles

  1. Default deny — Always start with read-only mode.
  2. Least privilege — Enable only the tools needed for the task.
  3. Explicit consent — Every destructive operation requires user approval.
  4. Defense in depth — Multiple layers of protection: operating mode, tool filtering, sandboxing, and path validation.

Operating Modes

Mode Description When to Use
readonly All write tools return denial Default for untrusted projects
write Write tools available with approval Trusted projects, active design
manufacturing Export tools + quality gates Release preparation
experimental All tools including auto-fix loops Advanced users only

Path Safety

  • KICAD_MCP_PROJECT_DIR is required and enforced
  • Path traversal attacks are blocked
  • Workspace-relative paths are validated
  • No write access outside the project directory
  • KICAD_MCP_OUTPUT_DIR limits export destinations

Prompt Injection Defense

KiCad project files (schematic text, net names, component values, BOM notes) are untrusted inputs:

  • No system prompt override from project file content
  • No command injection from net names, reference designators, or file names
  • DRC/ERC reports treated as data, not instructions
  • BOM supplier URLs treated as untrusted
  • All output paths sanitized before use

Remote Web Apps

Remote web apps (ChatGPT, Claude.ai) cannot directly access your local KiCad installation unless you explicitly run a local bridge:

  1. Remote tools are read-only by default
  2. Uploaded project archives are analyzed in an isolated environment
  3. Local bridge requires explicit pairing with user approval
  4. All bridge sessions are short-lived with rotating tokens

Sandboxing

VS Code and other MCP hosts support sandboxing: - Filesystem: Restrict read/write to specific directories - Network: Restrict allowed domains for outbound connections - Deny access to sensitive paths (~/.ssh, ~/.gnupg, etc.)

Tool Metadata

Each tool includes metadata for security decisions:

{
  "readOnlyHint": true,
  "destructiveHint": false,
  "requiresLocalFilesystem": true,
  "category": "analysis"
}

Write Tool Approval

Write tools require at one of these protections: 1. Operating mode readonly blocks all writes 2. Tool filtering (include/exclude lists) limits available tools 3. Agent-level approval (prompt/never/per-tool) 4. Sandbox restricts filesystem access

Best Practices

# Start safe
export KICAD_MCP_OPERATING_MODE=readonly

# For trusted projects, enable write mode
export KICAD_MCP_OPERATING_MODE=write

# Set project root explicitly
export KICAD_MCP_PROJECT_DIR=/path/to/project
  • Review all tool calls before approving destructive operations
  • Never enable write mode for projects from untrusted sources
  • Use kicad-mcp-pro doctor to audit your current configuration
  • Keep the server and dependencies updated