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

  1. Create a new scanner in scanner/scanners/
  2. Extend AbstractScanner
  3. Implement the scan() method
  4. 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

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