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

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.

mcp-watch

Author

kapilduraphe

Quick Info

Actions

Tags