Metadata-Version: 2.5
Name: mcp-hygiene
Version: 0.2.0
Summary: Offline security scanner for MCP servers. Detects tool poisoning, credential exposure, and dangerous permissions before you connect.
Project-URL: Homepage, https://github.com/liukefan821/mcp-doctor
Project-URL: Issues, https://github.com/liukefan821/mcp-doctor/issues
Author: Kefan Liu
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,mcp,scanner,security,tool-poisoning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# 🩺 mcp-doctor

**Offline security scanner for MCP servers.**  
Detects tool poisoning, credential exposure, and dangerous permissions — before you connect.

```bash
pip install mcp-doctor
mcp-doctor scan
```

## Why

The MCP ecosystem grew to 10,000+ servers in 18 months. Most developers connect servers without any security review. Meanwhile:

- **Tool poisoning** hides malicious instructions in tool descriptions that the AI reads but the user never sees ([MCPTox, AAAI 2026](https://arxiv.org/abs/2508.14925))
- **24,008 secrets** were found in public MCP config files ([GitGuardian, 2026](https://www.gitguardian.com))
- **CVE-2025-54136** showed shared-repo MCP configs can be weaponized across teams

`mcp-doctor` scans your MCP configs **locally and offline** — nothing leaves your machine.

## What it checks

| Rule | ID | Severity | What it detects |
|------|----|----------|-----------------|
| Tool Poisoning | TP-001 | CRITICAL | Hidden instructions in tool descriptions (prompt injection) |
| Unicode Concealment | TP-002 | HIGH | Invisible Unicode characters hiding payloads |
| Hardcoded Secrets | CE-001 | CRITICAL | API keys and tokens in config files |
| Secret Env Vars | CE-002 | HIGH | Literal secret values in env blocks |
| Shell Access | DP-001 | CRITICAL | Servers that grant direct shell execution |
| Broad FS Access | DP-002 | HIGH | Filesystem access to root or home directory |
| Unencrypted HTTP | TS-001 | HIGH | Non-localhost MCP connections over plain HTTP |
| Remote Endpoint | TS-002 | MEDIUM | Connections to remote servers (verify auth) |
| Unverified Package | CX-001 | MEDIUM | `npx -y` auto-install of unknown npm packages |
| Inline Code Exec | CX-002 | HIGH | `python -c` / `node -e` inline code execution |
| Long Argument | CX-003 | MEDIUM | Suspiciously long args (possible obfuscated payload) |
| Large Tool Surface | SC-001 | LOW | Servers exposing 25+ tools (increased attack surface) |

## Usage

```bash
# Auto-detect configs (Claude Desktop, Cursor, VS Code, project-level)
mcp-doctor scan

# Scan a specific config file
mcp-doctor scan path/to/config.json

# JSON output (for CI pipelines)
mcp-doctor scan --output json

# Search a project directory for MCP configs
mcp-doctor scan --dir /path/to/project
```

## Example output

```
🩺 mcp-doctor scan report
Config: ~/.config/Claude/claude_desktop_config.json
Servers scanned: 4

🔴 CRITICAL  TP-001  evil-server    Prompt injection in tool description
🔴 CRITICAL  CE-001  leaky-server   Hardcoded Anthropic API key
🔴 CRITICAL  DP-001  shell-access   Shell execution access
🟠 HIGH      CE-002  leaky-server   Secret in env: OPENAI_API_KEY
🟠 HIGH      TS-001  unsafe-remote  Unencrypted HTTP transport

  CRITICAL 3 | HIGH 2

  FAIL — critical findings require action.
```

## CI Integration

`mcp-doctor` exits with code 1 when critical findings are present:

```yaml
# .github/workflows/mcp-check.yml
- run: pip install mcp-doctor
- run: mcp-doctor scan --output json > mcp-report.json
```

## Privacy

- **Fully offline** — no API calls, no telemetry, no data sent anywhere
- Config contents are analyzed in-process and never written to disk
- Unlike some alternatives, your tool schemas are never sent to external servers

## License

MIT
