Content
# 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
- **Dependency Update**: Weekly dependency maintenance and security fixes
- **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.
Connection Info
You Might Also Like
No recommendations available