mcp-watch

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)

# 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

Installation

Global Installation

npm install -g mcp-watch

Local Installation

npm install mcp-watch

From Source

git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch
npm install
npm run build

Docker Installation 🐳

Quick Start with Docker

# 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)

# 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

# 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

# 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

# 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

# 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 🐳

# 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

# 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)

# 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 🐳

# 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

• Create a new scanner in scanner/scanners/
• Extend AbstractScanner
• Implement the scan() method
• Add to MCPScanner.ts

Example:

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)

  • Comprehensive database of MCP vulnerabilities
  • Real-world attack patterns and examples
  • Regular updates on new attack vectors

• HiddenLayer Research (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)

  • 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)

  • Conversation exfiltration methods
  • ANSI injection attacks
  • Protocol-level vulnerabilities
  • Insecure credential storage patterns
  • Cross-server shadowing attacks

• PromptHub Analysis (5 MCP Security Vulnerabilities)

  • 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

• Fork the repository
• Create a feature branch
• Run type checking with npm run type-check
• Test your changes manually
• 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 for detailed workflow documentation.

Docker Development Workflow 🐳

# 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 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 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.