{"_id":"@agentopssec/mcp-doctor","name":"@agentopssec/mcp-doctor","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agentopssec/mcp-doctor","version":"1.0.0","description":"Local-first MCP configuration security scanner.","type":"module","homepage":"https://AgentOpsSec.com/projects/mcp-doctor","repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/mcp-doctor.git"},"bugs":{"url":"https://github.com/AgentOpsSec/mcp-doctor/issues"},"bin":{"mcp-doctor":"bin/mcp-doctor.js"},"scripts":{"test":"node --test","check":"node --check bin/mcp-doctor.js && node --test","scan:fixture":"node ./bin/mcp-doctor.js scan --config test/fixtures/claude_desktop_config.json"},"keywords":["mcp","security","scanner","agent","cli"],"license":"MIT","engines":{"node":">=20"},"publishConfig":{"access":"public"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"gitHead":"40b777b22d326ec2e25b4f22646e5eb03cf91dac","_id":"@agentopssec/mcp-doctor@1.0.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-TWhKoczZEMvKQxv6UIXCr4OHdsVOKLu9d7afDxRivxD9ZZnJAi9HxstcbJndBr/u3JnTjECR6zHoGgT3kBy/1A==","shasum":"6f39b1001c293bc716986aeb1c61c178acf41156","tarball":"https://registry.npmjs.org/@agentopssec/mcp-doctor/-/mcp-doctor-1.0.0.tgz","fileCount":19,"unpackedSize":81602,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCQZjOQ9ye1HndC63GcsCu1iUVfQnS9/Mi9hw/wddd5iAIgfMerglW9OZDjeLIpa01BVXBwXdHUsxhQXMlEMWZPAuk="}]},"_npmUser":{"name":"agentopssec","email":"agentopssecurity@gmail.com"},"directories":{},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-doctor_1.0.0_1777236619984_0.8712383838224178"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T20:50:19.887Z","1.0.0":"2026-04-26T20:50:20.152Z","modified":"2026-04-26T20:50:20.328Z"},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"description":"Local-first MCP configuration security scanner.","homepage":"https://AgentOpsSec.com/projects/mcp-doctor","keywords":["mcp","security","scanner","agent","cli"],"repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/mcp-doctor.git"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"bugs":{"url":"https://github.com/AgentOpsSec/mcp-doctor/issues"},"license":"MIT","readme":"# MCP Doctor\n\n**Audit your MCP servers before your AI agent uses them.**\n\nMCP Doctor is a local-first security scanner for Model Context Protocol\nconfigurations. It helps developers see which MCP servers are installed, what\nthose servers can access, and which configurations introduce obvious risk before\nan AI agent starts using them.\n\nThink of it as:\n\n```txt\nnpm audit for MCP servers\n```\n\n## Why This Exists\n\nAI agents are no longer limited to chat. They can read files, run commands,\nopen browsers, query databases, call APIs, and modify systems through MCP\nservers and other tool integrations.\n\nThat power is useful, but it creates a basic visibility problem:\n\n- Which MCP servers are configured on this machine or project?\n- What tools do those servers expose?\n- Can they read or write files?\n- Can they execute shell commands?\n- Can they reach the network, GitHub, databases, email, or calendars?\n- Are secrets exposed through environment variables?\n- Are packages pinned and installed safely?\n- Which servers should be limited, reviewed, or removed?\n\nMCP Doctor answers those questions quickly from the command line.\n\n## Install\n\n```bash\nnpm install -g @agentopssec/mcp-doctor\n```\n\nOr run it without installing:\n\n```bash\nnpx -y @agentopssec/mcp-doctor scan\n```\n\n## Update\n\n```bash\nmcp-doctor update          # check the registry, prompt before installing\nmcp-doctor update --yes    # update without prompting (CI-safe)\n```\n\n`mcp-doctor --version` shows the running version.\n\n## Primary Workflow\n\nMCP Doctor starts with one focused command:\n\n```bash\nmcp-doctor scan\n```\n\nThe scan should do three things well:\n\n1. Find MCP servers.\n2. Show what they can access.\n3. Flag obvious risk clearly.\n\n## Local Development\n\nMCP Doctor is a dependency-free Node.js CLI.\n\n```bash\nnpm test\nnode ./bin/mcp-doctor.js scan\nnode ./bin/mcp-doctor.js scan --config test/fixtures/claude_desktop_config.json\n```\n\nTo use the local binary while developing:\n\n```bash\nnpm link\nmcp-doctor scan\n```\n\n## CLI\n\n```bash\nmcp-doctor scan\nmcp-doctor scan --config ~/.config/claude/claude_desktop_config.json\nmcp-doctor scan --json --output latest-scan.json\nmcp-doctor report --json\nmcp-doctor explain shell.exec\nmcp-doctor init-policy --path mcp-doctor.policy.json\nmcp-doctor ci --max-risk medium\nmcp-doctor diff previous-scan.json latest-scan.json\nmcp-doctor fix-suggestions latest-scan.json\nmcp-doctor update [--yes]\n```\n\n### `scan`\n\nScans discovered MCP configuration files and prints a terminal report.\n\n```bash\nmcp-doctor scan\nmcp-doctor scan --config ./mcp.json\nmcp-doctor scan --json\nmcp-doctor scan --output latest-scan.json\n```\n\nOptions:\n\n- `--config path`: scan a specific config file. Can be repeated.\n- `--cwd path`: use a specific project directory for discovery and policy checks.\n- `--json`: print the structured JSON report.\n- `--output path`: write the JSON report to a file.\n\n### `report`\n\nAlias for `scan`, useful when JSON output is the main workflow.\n\n```bash\nmcp-doctor report --json\n```\n\n### `explain`\n\nExplains why a tool, permission, or risk pattern matters.\n\n```bash\nmcp-doctor explain shell.exec\nmcp-doctor explain filesystem.home_access\nmcp-doctor explain package.unpinned\n```\n\n### `init-policy`\n\nWrites a starter policy file.\n\n```bash\nmcp-doctor init-policy\nmcp-doctor init-policy --path .agentopssec/mcp-doctor.policy.json\nmcp-doctor init-policy --force\n```\n\n### `ci`\n\nRuns a scan and exits with code `1` when the highest detected risk is above the\nconfigured threshold.\n\n```bash\nmcp-doctor ci\nmcp-doctor ci --max-risk low\nmcp-doctor ci --json\n```\n\nThe default threshold is `medium`, which means `high` and `critical` findings\nfail CI.\n\n### `diff`\n\nCompares two scan reports.\n\n```bash\nmcp-doctor diff previous-scan.json latest-scan.json\nmcp-doctor diff previous-scan.json latest-scan.json --json\nmcp-doctor diff previous-scan.json latest-scan.json --ci\n```\n\n### `fix-suggestions`\n\nTurns scan findings into concrete hardening actions.\n\n```bash\nmcp-doctor fix-suggestions\nmcp-doctor fix-suggestions latest-scan.json\nmcp-doctor fix-suggestions latest-scan.json --json\n```\n\n## Standalone and Stack Use\n\nMCP Doctor runs on its own as a local MCP configuration scanner:\n\n```bash\nmcp-doctor scan\nmcp-doctor scan --json --output mcp-doctor-scan.json\n```\n\nWhen used with the full AgentOpsSec stack, its JSON reports can feed MCP\nFirewall and MCP Radar without those tools importing MCP Doctor code:\n\n```bash\nmcp-firewall import-doctor mcp-doctor-scan.json\nmcp-radar score-doctor mcp-doctor-scan.json\n```\n\n## What MCP Doctor Checks\n\nMCP Doctor scans local and project-level MCP configuration and looks for:\n\n- Installed MCP servers\n- MCP config files\n- Tool permissions\n- Filesystem access\n- Shell access\n- Network or browser access\n- GitHub access\n- Database access\n- Email or calendar access\n- Environment variable exposure\n- Unpinned packages\n- Local script execution\n- Suspicious install methods\n- Duplicate tools\n- Overly broad access scopes\n- Missing policy files\n\n## Example Output\n\n```txt\nMCP Doctor Scan by github.com/AgentOpsSec\n\nFound 7 MCP servers\n\nHIGH RISK\n- filesystem\n  Access: read/write\n  Scope: /Users/steven\n  Issue: Broad filesystem access\n  Recommendation: Limit to the project directory\n\n- shell\n  Access: command execution\n  Issue: Agent can run arbitrary commands\n  Recommendation: Require approval for shell.exec\n\nMEDIUM RISK\n- github\n  Access: repo read/write\n  Issue: Token may allow branch and pull request changes\n  Recommendation: Use a least-privilege token\n\nLOW RISK\n- docs-search\n  Access: read-only docs\n  Issue: none detected\n\nScore: C+\n```\n\n## Risk Categories\n\nMCP Doctor classifies exposed tools and configuration patterns into categories:\n\n```txt\nfilesystem\nshell\nnetwork\nsecrets\ndatabase\ngithub\ncloud\nbrowser\nemail\ncalendar\npayments\nauth\nci_cd\ndependencies\nproduction\n```\n\nRisk levels:\n\n```txt\nlow\nmedium\nhigh\ncritical\n```\n\n## Starter Policy\n\nMCP Doctor can generate a starter policy file for teams that want to make MCP\nusage more explicit and reviewable.\n\n```json\n{\n  \"rules\": {\n    \"filesystem.write\": \"warn\",\n    \"filesystem.home_access\": \"block\",\n    \"shell.exec\": \"warn\",\n    \"network.external\": \"warn\",\n    \"github.write\": \"warn\",\n    \"email.send\": \"block\",\n    \"calendar.write\": \"warn\"\n  }\n}\n```\n\nSupported actions:\n\n```txt\nallow\nwarn\nblock\napprove_once\napprove_for_session\napprove_for_project\nlog_only\n```\n\n## JSON Output\n\nMCP Doctor is designed to be usable by humans and automation. CI mode and JSON\nreports should make it possible to fail builds, track drift, or compare scans\nover time.\n\nExample shape:\n\n```json\n{\n  \"tool\": {\n    \"name\": \"MCP Doctor\",\n    \"by\": \"github.com/AgentOpsSec\",\n    \"repository\": \"github.com/AgentOpsSec/mcp-doctor\"\n  },\n  \"summary\": {\n    \"serversFound\": 7,\n    \"score\": \"C+\",\n    \"highestRisk\": \"high\"\n  },\n  \"findings\": [\n    {\n      \"server\": \"filesystem\",\n      \"category\": \"filesystem\",\n      \"risk\": \"high\",\n      \"issue\": \"Broad filesystem access\",\n      \"recommendation\": \"Limit to the project directory\"\n    }\n  ]\n}\n```\n\n## Design Principles\n\n- Local-first\n- Open-source\n- No telemetry by default\n- Human-readable output\n- CI-friendly reports\n- Transparent risk rules\n- Secure defaults\n- Practical recommendations\n\n## Initial Release Scope\n\nThe initial release includes the core scan, automation and policy output, and\nchange detection workflows.\n\n### 1.0: Core Scan\n\n- Detect common MCP configuration locations\n- Parse MCP server definitions\n- List configured MCP servers\n- Identify broad tool categories\n- Detect filesystem access\n- Detect shell access\n- Detect network/browser access\n- Flag unpinned or unknown packages\n- Print a clear terminal report\n\n### 1.0: Automation and Policy\n\n- JSON report output\n- Basic CI mode\n- Starter policy generation\n- `explain` command for risk education\n- Better recommendations by risk category\n\n### 1.0: Change Detection\n\n- Compare two scan reports\n- Highlight new, removed, or changed servers\n- Track score changes over time\n- Improve project-level configuration support\n\n\n## Output\n\nReports use plain-language status words rather than raw exit codes:\n\n- `ok` — the step ran successfully (green).\n- `failed (exit N)` — the step exited non-zero (red); the original code is preserved.\n- `skipped (reason)` — the step was not applicable (dim).\n\nSeverity 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.\n\n\n- Repo: https://github.com/AgentOpsSec/mcp-doctor\n- npm: https://www.npmjs.com/package/@agentopssec/mcp-doctor\n- AgentOpsSec stack: https://github.com/AgentOpsSec/stack\n- Website: https://AgentOpsSec.com\n\n## Author\n\nCreated and developed by **Aunt Gladys Nephew**.\n\n- Website: https://auntgladysnephew.com\n- GitHub: https://github.com/auntgladysnephew\n- X: https://x.com/AGNonX\n","readmeFilename":"README.md","_rev":"1-2ae940828ac34e7f60e10a9b5c00ba29"}