MCP Doctor

Audit your MCP servers before your AI agent uses them.

MCP Doctor is a local-first security scanner for Model Context Protocol configurations. It helps developers see which MCP servers are installed, what those servers can access, and which configurations introduce obvious risk before an AI agent starts using them.

Think of it as:

npm audit for MCP servers

Why This Exists

AI agents are no longer limited to chat. They can read files, run commands, open browsers, query databases, call APIs, and modify systems through MCP servers and other tool integrations.

That power is useful, but it creates a basic visibility problem:

• Which MCP servers are configured on this machine or project?
• What tools do those servers expose?
• Can they read or write files?
• Can they execute shell commands?
• Can they reach the network, GitHub, databases, email, or calendars?
• Are secrets exposed through environment variables?
• Are packages pinned and installed safely?
• Which servers should be limited, reviewed, or removed?

MCP Doctor answers those questions quickly from the command line.

Install

npm install -g @agentopssec/mcp-doctor

Or run it without installing:

npx -y @agentopssec/mcp-doctor scan

Update

mcp-doctor update          # check the registry, prompt before installing
mcp-doctor update --yes    # update without prompting (CI-safe)

mcp-doctor --version shows the running version.

Primary Workflow

MCP Doctor starts with one focused command:

mcp-doctor scan

The scan should do three things well:

1. Find MCP servers.
2. Show what they can access.
3. Flag obvious risk clearly.

Local Development

MCP Doctor is a dependency-free Node.js CLI.

npm test
node ./bin/mcp-doctor.js scan
node ./bin/mcp-doctor.js scan --config test/fixtures/claude_desktop_config.json

To use the local binary while developing:

npm link
mcp-doctor scan

CLI

mcp-doctor scan
mcp-doctor scan --config ~/.config/claude/claude_desktop_config.json
mcp-doctor scan --json --output latest-scan.json
mcp-doctor report --json
mcp-doctor explain shell.exec
mcp-doctor init-policy --path mcp-doctor.policy.json
mcp-doctor ci --max-risk medium
mcp-doctor diff previous-scan.json latest-scan.json
mcp-doctor fix-suggestions latest-scan.json
mcp-doctor update [--yes]

scan

Scans discovered MCP configuration files and prints a terminal report.

mcp-doctor scan
mcp-doctor scan --config ./mcp.json
mcp-doctor scan --json
mcp-doctor scan --output latest-scan.json

Options:

• --config path: scan a specific config file. Can be repeated.
• --cwd path: use a specific project directory for discovery and policy checks.
• --json: print the structured JSON report.
• --output path: write the JSON report to a file.

report

Alias for scan, useful when JSON output is the main workflow.

mcp-doctor report --json

explain

Explains why a tool, permission, or risk pattern matters.

mcp-doctor explain shell.exec
mcp-doctor explain filesystem.home_access
mcp-doctor explain package.unpinned

init-policy

Writes a starter policy file.

mcp-doctor init-policy
mcp-doctor init-policy --path .agentopssec/mcp-doctor.policy.json
mcp-doctor init-policy --force

ci

Runs a scan and exits with code 1 when the highest detected risk is above the configured threshold.

mcp-doctor ci
mcp-doctor ci --max-risk low
mcp-doctor ci --json

The default threshold is medium, which means high and critical findings fail CI.

diff

Compares two scan reports.

mcp-doctor diff previous-scan.json latest-scan.json
mcp-doctor diff previous-scan.json latest-scan.json --json
mcp-doctor diff previous-scan.json latest-scan.json --ci

fix-suggestions

Turns scan findings into concrete hardening actions.

mcp-doctor fix-suggestions
mcp-doctor fix-suggestions latest-scan.json
mcp-doctor fix-suggestions latest-scan.json --json

Standalone and Stack Use

MCP Doctor runs on its own as a local MCP configuration scanner:

mcp-doctor scan
mcp-doctor scan --json --output mcp-doctor-scan.json

When used with the full AgentOpsSec stack, its JSON reports can feed MCP Firewall and MCP Radar without those tools importing MCP Doctor code:

mcp-firewall import-doctor mcp-doctor-scan.json
mcp-radar score-doctor mcp-doctor-scan.json

What MCP Doctor Checks

MCP Doctor scans local and project-level MCP configuration and looks for:

• Installed MCP servers
• MCP config files
• Tool permissions
• Filesystem access
• Shell access
• Network or browser access
• GitHub access
• Database access
• Email or calendar access
• Environment variable exposure
• Unpinned packages
• Local script execution
• Suspicious install methods
• Duplicate tools
• Overly broad access scopes
• Missing policy files

Example Output

MCP Doctor Scan by github.com/AgentOpsSec

Found 7 MCP servers

HIGH RISK
- filesystem
  Access: read/write
  Scope: /Users/steven
  Issue: Broad filesystem access
  Recommendation: Limit to the project directory

- shell
  Access: command execution
  Issue: Agent can run arbitrary commands
  Recommendation: Require approval for shell.exec

MEDIUM RISK
- github
  Access: repo read/write
  Issue: Token may allow branch and pull request changes
  Recommendation: Use a least-privilege token

LOW RISK
- docs-search
  Access: read-only docs
  Issue: none detected

Score: C+

Risk Categories

MCP Doctor classifies exposed tools and configuration patterns into categories:

filesystem
shell
network
secrets
database
github
cloud
browser
email
calendar
payments
auth
ci_cd
dependencies
production

Risk levels:

low
medium
high
critical

Starter Policy

MCP Doctor can generate a starter policy file for teams that want to make MCP usage more explicit and reviewable.

{
  "rules": {
    "filesystem.write": "warn",
    "filesystem.home_access": "block",
    "shell.exec": "warn",
    "network.external": "warn",
    "github.write": "warn",
    "email.send": "block",
    "calendar.write": "warn"
  }
}

Supported actions:

allow
warn
block
approve_once
approve_for_session
approve_for_project
log_only

JSON Output

MCP Doctor is designed to be usable by humans and automation. CI mode and JSON reports should make it possible to fail builds, track drift, or compare scans over time.

Example shape:

{
  "tool": {
    "name": "MCP Doctor",
    "by": "github.com/AgentOpsSec",
    "repository": "github.com/AgentOpsSec/mcp-doctor"
  },
  "summary": {
    "serversFound": 7,
    "score": "C+",
    "highestRisk": "high"
  },
  "findings": [
    {
      "server": "filesystem",
      "category": "filesystem",
      "risk": "high",
      "issue": "Broad filesystem access",
      "recommendation": "Limit to the project directory"
    }
  ]
}

Design Principles

• Local-first
• Open-source
• No telemetry by default
• Human-readable output
• CI-friendly reports
• Transparent risk rules
• Secure defaults
• Practical recommendations

Initial Release Scope

The initial release includes the core scan, automation and policy output, and change detection workflows.

1.0: Core Scan

• Detect common MCP configuration locations
• Parse MCP server definitions
• List configured MCP servers
• Identify broad tool categories
• Detect filesystem access
• Detect shell access
• Detect network/browser access
• Flag unpinned or unknown packages
• Print a clear terminal report

1.0: Automation and Policy

• JSON report output
• Basic CI mode
• Starter policy generation
• explain command for risk education
• Better recommendations by risk category

1.0: Change Detection

• Compare two scan reports
• Highlight new, removed, or changed servers
• Track score changes over time
• Improve project-level configuration support

Output

Reports use plain-language status words rather than raw exit codes:

• ok — the step ran successfully (green).
• failed (exit N) — the step exited non-zero (red); the original code is preserved.
• skipped (reason) — the step was not applicable (dim).

Severity colors follow the AgentOpsSec palette (safe = green, warning = amber, risk = red). The palette honors NO_COLOR and FORCE_COLOR, and JSON / CSV output stays plain.

• Repo: https://github.com/AgentOpsSec/mcp-doctor
• npm: https://www.npmjs.com/package/@agentopssec/mcp-doctor
• AgentOpsSec stack: https://github.com/AgentOpsSec/stack
• Website: https://AgentOpsSec.com

Author

Created and developed by Aunt Gladys Nephew.

• Website: https://auntgladysnephew.com
• GitHub: https://github.com/auntgladysnephew
• X: https://x.com/AGNonX