mcp-watch
A comprehensive security scanner for Model Context Protocol (MCP) servers that detects vulnerabilities and security issues in your MCP server implementations.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/kapilduraphe--mcp-watch)HTML
<a href="/listings/kapilduraphe--mcp-watch"><img src="/api/listings/kapilduraphe--mcp-watch/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Option 1: NPM Package (Recommended)
# Install globally npm install -g mcp-watch # Scan any GitHub MCP repository mcp-watch scan https://github.com/user/mcp-server # Scan your local MCP project mcp-watch scan-local /path/to/your/mcp-project
Option 2: From GitHub Source
# Clone and use immediately git clone https://github.com/kapilduraphe/mcp-watch.git cd mcp-watch npm install npm run build # Scan GitHub repos npm run scan:github https://github.com/user/mcp-server # Scan local projects npm run scan:local /path/to/your/mcp-project
Option 3: Docker (No Installation)
# Scan without installing anything docker run --rm mcp-watch scan https://github.com/user/mcp-server docker run --rm -v $(pwd):/workspace mcp-watch scan-local /workspace
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 448 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # MCP Watch 🔍
- A comprehensive security scanner for Model Context Protocol (MCP) servers that detects vulnerabilities and security issues in your MCP implementations.
- ## Features
- - **🔑 Credential Detection** - Finds hardcoded API keys, tokens, and insecure credential storage
- - **🧪 Tool Poisoning** - Detects hidden malicious instructions in tool descriptions
- - **🎯 Parameter Injection** - Identifies magic parameters that extract sensitive AI context
- - **💉 Prompt Injection** - Scans for prompt manipulation and injection attacks
- - **🔄 Tool Mutation** - Detects dynamic tool changes and rug-pull risks
- - **💬 Conversation Exfiltration** - Finds triggers that steal conversation history
- - **🎨 ANSI Injection** - Detects steganographic attacks using escape sequences
- - **📋 Protocol Violations** - Identifies MCP protocol security violations
- - **🛡️ Input Validation** - Finds command injection, SSRF, and path traversal issues
- - **🎭 Server Spoofing** - Detects servers impersonating popular services
- - **🌊 Toxic Flows** - Identifies dangerous data flow patterns
- - **🔐 Permission Issues** - Finds excessive permissions and access control problems
- ## Quick Start 🚀
- ### Option 1: NPM Package (Recommended)
- ```bash
- # Install globally
- npm install -g mcp-watch
- # Scan any GitHub MCP repository
- mcp-watch scan https://github.com/user/mcp-server
- # Scan your local MCP project
- mcp-watch scan-local /path/to/your/mcp-project
- ```
- ### Option 2: From GitHub Source
- ```bash
- # Clone and use immediately
- git clone https://github.com/kapilduraphe/mcp-watch.git
- cd mcp-watch
- npm install
- npm run build
- # Scan GitHub repos
- npm run scan:github https://github.com/user/mcp-server
- # Scan local projects
- npm run scan:local /path/to/your/mcp-project
- ```
- ### Option 3: Docker (No Installation)
- ```bash
- # Scan without installing anything
- docker run --rm mcp-watch scan https://github.com/user/mcp-server
- docker run --rm -v $(pwd):/workspace mcp-watch scan-local /workspace
- ```
- ## Installation
- ### Global Installation
- ```bash
- npm install -g mcp-watch
- ```
- ### Local Installation
- ```bash
- npm install mcp-watch
- ```
- ### From Source
- ```bash
- git clone https://github.com/kapilduraphe/mcp-watch.git
- cd mcp-watch
- npm install
- npm run build
- ```
- ### Docker Installation 🐳
- #### Quick Start with Docker
- ```bash
- # Build and run locally
- docker build -t mcp-watch .
- docker run --rm mcp-watch scan https://github.com/user/mcp-server
- # Build from source
- git clone https://github.com/kapilduraphe/mcp-watch.git
- cd mcp-watch
- docker build -t mcp-watch .
- ```
- #### Docker Compose (Recommended for Production)
- ```bash
- # Build and run with Docker Compose
- docker compose build
- docker compose up mcp-watch
- # Or run a one-off scan
- docker compose run --rm mcp-watch scan https://github.com/user/repo
- ```
- #### Docker Features
- - **🔒 Security**: Non-root user, minimal attack surface
- - **📦 Optimized**: Multi-stage builds, Alpine Linux base
- - **🚀 Production**: Ready for deployment and CI/CD
- - **🧹 Simplified**: Single optimized Dockerfile for all use cases
- ## Usage
- ### Command Line
- #### Scan GitHub Repositories
- ```bash
- # Scan a GitHub repository
- mcp-watch scan https://github.com/user/mcp-server
- # Scan with JSON output
- mcp-watch scan https://github.com/user/mcp-server --format json
- # Filter by severity
- mcp-watch scan https://github.com/user/mcp-server --severity high
- # Filter by category
- mcp-watch scan https://github.com/user/mcp-server --category credential-leak
- ```
- #### Scan Local Projects
- ```bash
- # Scan current directory
- mcp-watch scan-local .
- # Scan specific directory (absolute path)
- mcp-watch scan-local /path/to/your/mcp-project
- # Scan specific directory (relative path)
- mcp-watch scan-local ../my-mcp-server
- # Local scan with JSON output
- mcp-watch scan-local . --format json
- # Local scan with severity filter
- mcp-watch scan-local . --severity high
- ```
- ### Installation Method Usage
- #### From NPM Package
- ```bash
- # Global installation (recommended)
- npm install -g mcp-watch
- mcp-watch scan https://github.com/user/mcp-server
- mcp-watch scan-local /path/to/project
- ```
- #### From GitHub Source
- ```bash
- # Clone and build
- git clone https://github.com/kapilduraphe/mcp-watch.git
- cd mcp-watch
- npm install
- npm run build
- # Use built version
- node dist/main.js scan https://github.com/user/mcp-server
- node dist/main.js scan-local /path/to/project
- # Or use npm scripts
- npm run scan https://github.com/user/mcp-server
- npm run scan-local /path/to/project
- ```
- ### Docker Usage 🐳
- ```bash
- # Production container
- docker run --rm mcp-watch scan https://github.com/user/mcp-server
- docker run --rm mcp-watch scan https://github.com/user/mcp-server --format json --severity high
- # Docker Compose
- docker compose run --rm mcp-watch scan https://github.com/user/repo
- docker compose run --rm mcp-watch scan https://github.com/user/repo --format json
- # Interactive container
- docker run -it --rm mcp-watch sh
- ```
- ### Options
- - `--format <type>` - Output format: `console` (default) or `json`
- - `--severity <level>` - Minimum severity: `low`, `medium`, `high`, `critical`
- - `--category <cat>` - Filter by vulnerability category
- ### Categories
- - `credential-leak` - Hardcoded credentials and insecure storage
- - `tool-poisoning` - Malicious tool descriptions
- - `data-exfiltration` - Data theft and parameter injection
- - `prompt-injection` - Prompt manipulation attacks
- - `tool-mutation` - Dynamic tool changes
- - `steganographic-attack` - Hidden content in escape sequences
- - `protocol-violation` - MCP protocol security issues
- - `input-validation` - Command injection, SSRF, path traversal
- - `server-spoofing` - Server impersonation
- - `toxic-flow` - Dangerous data flows
- - `access-control` - Permission and access issues
- ## Example Output
- ```
- 🔍 Scanning repository: https://github.com/user/mcp-server
- 📊 Based on vulnerablemcp.info, HiddenLayer, Invariant Labs, and Trail of Bits research
- 🔑 Scanning for credential vulnerabilities...
- 🧪 Scanning for tool poisoning vulnerabilities...
- 🎯 Scanning for parameter injection vulnerabilities...
- 💉 Scanning for prompt injection vulnerabilities...
- 📊 MCP SECURITY SCAN RESULTS
- ===============================
- 📈 Summary by Severity:
- 🚨 CRITICAL: 2
- ⚠️ HIGH: 1
- ⚡ MEDIUM: 3
- 🔍 Detailed Results:
- --------------------
- 1. 🚨 Hardcoded credentials detected
- 📋 ID: HARDCODED_CREDENTIALS
- 🎯 Severity: CRITICAL
- 📂 Category: credential-leak
- 📍 Location: src/config.ts:15
- 🔍 Evidence: const apiKey = "sk-***REDACTED***"
- ```
- ## Development
- ### Project Structure
- ```
- mcp-watch/
- ├── main.ts # CLI entry point
- ├── types/
- │ └── Vulnerability.ts # Type definitions
- ├── scanner/
- │ ├── MCPScanner.ts # Main scanner orchestrator
- │ ├── BaseScanner.ts # Base scanner utilities
- │ └── scanners/ # Individual vulnerability scanners
- │ ├── CredentialScanner.ts
- │ ├── ParameterInjectionScanner.ts
- │ └── ...
- ├── utils/
- │ └── reportFormatter.ts # Report formatting
- └── Docker/ # Containerization
- ├── Dockerfile # Production image
- ├── docker-compose.yml # Multi-service orchestration (Docker Compose v2)
- └── .dockerignore # Build optimization
- ```
- ### Development Scripts
- ```bash
- # Build the project
- npm run build
- # Run in development mode
- npm run dev scan https://github.com/user/repo
- # Quick scan during development
- npm run scan https://github.com/user/repo
- # Clean build artifacts
- npm run clean
- # Type checking
- npm run type-check
- ```
- ### Development Workflow 🚀
- #### Local Development (Recommended)
- ```bash
- # Install dependencies
- npm install
- # Run development server
- npm run dev
- # Run scans during development
- npm run scan https://github.com/user/repo
- # Type checking
- npm run type-check
- ```
- #### Docker Development 🐳
- ```bash
- # Build Docker image
- docker compose build
- # Test the image
- docker run --rm mcp-watch scan https://github.com/user/repo
- # Test Docker Compose
- docker compose run --rm mcp-watch scan --help
- ```
- ### Adding New Scanners
- 1. Create a new scanner in `scanner/scanners/`
- 2. Extend `AbstractScanner`
- 3. Implement the `scan()` method
- 4. Add to `MCPScanner.ts`
- Example:
- ```typescript
- import { AbstractScanner } from "../BaseScanner";
- import { Vulnerability } from "../../types/Vulnerability";
- export class MyScanner extends AbstractScanner {
- async scan(projectPath: string): Promise<Vulnerability[]> {
- console.log("🔍 Scanning for my vulnerability type...");
- const vulnerabilities: Vulnerability[] = [];
- // Your scanning logic here
- return vulnerabilities;
- }
- }
- ```
- ## Security Research
- This tool is based on security research from leading organizations in AI and cybersecurity, identifying novel attack vectors specific to MCP environments including:
- - **Parameter injection attacks** that extract sensitive AI context
- - **Tool poisoning** with hidden malicious instructions
- - **Conversation exfiltration** using trigger phrases
- - **Steganographic attacks** via ANSI escape sequences
- - **Toxic agent flows** across repository boundaries
- ### Research Sources
- - **VulnerableMCP Database** ([vulnerablemcp.info](https://vulnerablemcp.info))
- - Comprehensive database of MCP vulnerabilities
- - Real-world attack patterns and examples
- - Regular updates on new attack vectors
- - **HiddenLayer Research** ([Exploiting MCP Tool Parameters](https://hiddenlayer.com/innovation-hub/exploiting-mcp-tool-parameters))
- - Parameter injection attacks that extract sensitive data
- - Tool call history and conversation exfiltration
- - System prompt extraction vulnerabilities
- - Chain of thought manipulation
- - Model name disclosure risks
- - **Invariant Labs Research** ([GitHub MCP Vulnerability](https://invariantlabs.ai/blog/mcp-github-vulnerability))
- - Tool poisoning detection
- - Toxic agent flows
- - Cross-repository security issues
- - Rug-pull updates in tool functionality
- - Server spoofing prevention
- - **Trail of Bits Research** ([MCP Security Research](https://blog.trailofbits.com/categories/mcp))
- - Conversation exfiltration methods
- - ANSI injection attacks
- - Protocol-level vulnerabilities
- - Insecure credential storage patterns
- - Cross-server shadowing attacks
- - **PromptHub Analysis** ([5 MCP Security Vulnerabilities](https://prompthub.substack.com/p/5-mcp-security-vulnerabilities-you))
- - Command injection patterns (43% of public MCP servers affected)
- - SSRF vulnerability statistics (30% allow arbitrary URL fetching)
- - Path traversal attack vectors (22% leak files outside intended directories)
- - Retrieval-Agent Deception (RADE) attacks
- - Tool poisoning prevention strategies
- ## Exit Codes
- - `0` - No critical or high severity vulnerabilities found
- - `1` - Critical or high severity vulnerabilities detected
- - `1` - Scan error occurred
- ## Contributing
- 1. Fork the repository
- 2. Create a feature branch
- 3. Run type checking with `npm run type-check`
- 4. Test your changes manually
- 5. Submit a pull request
- ## GitHub Actions 🚀
- This repository uses automated workflows for CI/CD, security scanning, and dependency management:
- - **CI**: Automated testing and Docker verification on every push/PR
- - **Security Scan**: Daily security audits and vulnerability checks
- - **Release**: Automated release asset creation
- - **Docker Test**: Docker-specific testing and validation
- ## Dependabot 🤖
- Automated dependency management with:
- - **npm**: Weekly updates with auto-merge for minor/patch versions
- - **GitHub Actions**: Automated action updates
- - **Docker**: Base image updates
- See [GITHUB_ACTIONS.md](GITHUB_ACTIONS.md) for detailed workflow documentation.
- ### Docker Development Workflow 🐳
- ```bash
- # Clone and setup
- git clone https://github.com/kapilduraphe/mcp-watch.git
- cd mcp-watch
- # Build Docker image
- docker compose build
- # Test the image
- docker run --rm mcp-watch --help
- # Run a scan
- docker compose run --rm mcp-watch scan https://github.com/user/repo
- ```
- ## License
- MIT License - see [LICENSE](LICENSE) file for details.
- ## Support
- - Create an issue for bug reports or feature requests
- - Check existing issues before creating new ones
- - Include scan output and repository details when reporting issues
- ### Docker Support 🐳
- - **Documentation**: See [DOCKER.md](DOCKER.md) for detailed Docker usage
- - **Issues**: Include Docker version and Docker Compose version when reporting issues
- - **Testing**: Test with both production and development containers
- ---
- **⚠️ Security Notice**: This tool identifies potential security issues but should not be the only security measure. Always perform manual security reviews and follow security best practices.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.