Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kapilduraphe--mcp-watch/badge.svg)](/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

i

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.

  1. # MCP Watch 🔍
  2. A comprehensive security scanner for Model Context Protocol (MCP) servers that detects vulnerabilities and security issues in your MCP implementations.
  3. ## Features
  4. - **🔑 Credential Detection** - Finds hardcoded API keys, tokens, and insecure credential storage
  5. - **🧪 Tool Poisoning** - Detects hidden malicious instructions in tool descriptions
  6. - **🎯 Parameter Injection** - Identifies magic parameters that extract sensitive AI context
  7. - **💉 Prompt Injection** - Scans for prompt manipulation and injection attacks
  8. - **🔄 Tool Mutation** - Detects dynamic tool changes and rug-pull risks
  9. - **💬 Conversation Exfiltration** - Finds triggers that steal conversation history
  10. - **🎨 ANSI Injection** - Detects steganographic attacks using escape sequences
  11. - **📋 Protocol Violations** - Identifies MCP protocol security violations
  12. - **🛡️ Input Validation** - Finds command injection, SSRF, and path traversal issues
  13. - **🎭 Server Spoofing** - Detects servers impersonating popular services
  14. - **🌊 Toxic Flows** - Identifies dangerous data flow patterns
  15. - **🔐 Permission Issues** - Finds excessive permissions and access control problems
  16. ## Quick Start 🚀
  17. ### Option 1: NPM Package (Recommended)
  18. ```bash
  19. # Install globally
  20. npm install -g mcp-watch
  21. # Scan any GitHub MCP repository
  22. mcp-watch scan https://github.com/user/mcp-server
  23. # Scan your local MCP project
  24. mcp-watch scan-local /path/to/your/mcp-project
  25. ```
  26. ### Option 2: From GitHub Source
  27. ```bash
  28. # Clone and use immediately
  29. git clone https://github.com/kapilduraphe/mcp-watch.git
  30. cd mcp-watch
  31. npm install
  32. npm run build
  33. # Scan GitHub repos
  34. npm run scan:github https://github.com/user/mcp-server
  35. # Scan local projects
  36. npm run scan:local /path/to/your/mcp-project
  37. ```
  38. ### Option 3: Docker (No Installation)
  39. ```bash
  40. # Scan without installing anything
  41. docker run --rm mcp-watch scan https://github.com/user/mcp-server
  42. docker run --rm -v $(pwd):/workspace mcp-watch scan-local /workspace
  43. ```
  44. ## Installation
  45. ### Global Installation
  46. ```bash
  47. npm install -g mcp-watch
  48. ```
  49. ### Local Installation
  50. ```bash
  51. npm install mcp-watch
  52. ```
  53. ### From Source
  54. ```bash
  55. git clone https://github.com/kapilduraphe/mcp-watch.git
  56. cd mcp-watch
  57. npm install
  58. npm run build
  59. ```
  60. ### Docker Installation 🐳
  61. #### Quick Start with Docker
  62. ```bash
  63. # Build and run locally
  64. docker build -t mcp-watch .
  65. docker run --rm mcp-watch scan https://github.com/user/mcp-server
  66. # Build from source
  67. git clone https://github.com/kapilduraphe/mcp-watch.git
  68. cd mcp-watch
  69. docker build -t mcp-watch .
  70. ```
  71. #### Docker Compose (Recommended for Production)
  72. ```bash
  73. # Build and run with Docker Compose
  74. docker compose build
  75. docker compose up mcp-watch
  76. # Or run a one-off scan
  77. docker compose run --rm mcp-watch scan https://github.com/user/repo
  78. ```
  79. #### Docker Features
  80. - **🔒 Security**: Non-root user, minimal attack surface
  81. - **📦 Optimized**: Multi-stage builds, Alpine Linux base
  82. - **🚀 Production**: Ready for deployment and CI/CD
  83. - **🧹 Simplified**: Single optimized Dockerfile for all use cases
  84. ## Usage
  85. ### Command Line
  86. #### Scan GitHub Repositories
  87. ```bash
  88. # Scan a GitHub repository
  89. mcp-watch scan https://github.com/user/mcp-server
  90. # Scan with JSON output
  91. mcp-watch scan https://github.com/user/mcp-server --format json
  92. # Filter by severity
  93. mcp-watch scan https://github.com/user/mcp-server --severity high
  94. # Filter by category
  95. mcp-watch scan https://github.com/user/mcp-server --category credential-leak
  96. ```
  97. #### Scan Local Projects
  98. ```bash
  99. # Scan current directory
  100. mcp-watch scan-local .
  101. # Scan specific directory (absolute path)
  102. mcp-watch scan-local /path/to/your/mcp-project
  103. # Scan specific directory (relative path)
  104. mcp-watch scan-local ../my-mcp-server
  105. # Local scan with JSON output
  106. mcp-watch scan-local . --format json
  107. # Local scan with severity filter
  108. mcp-watch scan-local . --severity high
  109. ```
  110. ### Installation Method Usage
  111. #### From NPM Package
  112. ```bash
  113. # Global installation (recommended)
  114. npm install -g mcp-watch
  115. mcp-watch scan https://github.com/user/mcp-server
  116. mcp-watch scan-local /path/to/project
  117. ```
  118. #### From GitHub Source
  119. ```bash
  120. # Clone and build
  121. git clone https://github.com/kapilduraphe/mcp-watch.git
  122. cd mcp-watch
  123. npm install
  124. npm run build
  125. # Use built version
  126. node dist/main.js scan https://github.com/user/mcp-server
  127. node dist/main.js scan-local /path/to/project
  128. # Or use npm scripts
  129. npm run scan https://github.com/user/mcp-server
  130. npm run scan-local /path/to/project
  131. ```
  132. ### Docker Usage 🐳
  133. ```bash
  134. # Production container
  135. docker run --rm mcp-watch scan https://github.com/user/mcp-server
  136. docker run --rm mcp-watch scan https://github.com/user/mcp-server --format json --severity high
  137. # Docker Compose
  138. docker compose run --rm mcp-watch scan https://github.com/user/repo
  139. docker compose run --rm mcp-watch scan https://github.com/user/repo --format json
  140. # Interactive container
  141. docker run -it --rm mcp-watch sh
  142. ```
  143. ### Options
  144. - `--format <type>` - Output format: `console` (default) or `json`
  145. - `--severity <level>` - Minimum severity: `low`, `medium`, `high`, `critical`
  146. - `--category <cat>` - Filter by vulnerability category
  147. ### Categories
  148. - `credential-leak` - Hardcoded credentials and insecure storage
  149. - `tool-poisoning` - Malicious tool descriptions
  150. - `data-exfiltration` - Data theft and parameter injection
  151. - `prompt-injection` - Prompt manipulation attacks
  152. - `tool-mutation` - Dynamic tool changes
  153. - `steganographic-attack` - Hidden content in escape sequences
  154. - `protocol-violation` - MCP protocol security issues
  155. - `input-validation` - Command injection, SSRF, path traversal
  156. - `server-spoofing` - Server impersonation
  157. - `toxic-flow` - Dangerous data flows
  158. - `access-control` - Permission and access issues
  159. ## Example Output
  160. ```
  161. 🔍 Scanning repository: https://github.com/user/mcp-server
  162. 📊 Based on vulnerablemcp.info, HiddenLayer, Invariant Labs, and Trail of Bits research
  163. 🔑 Scanning for credential vulnerabilities...
  164. 🧪 Scanning for tool poisoning vulnerabilities...
  165. 🎯 Scanning for parameter injection vulnerabilities...
  166. 💉 Scanning for prompt injection vulnerabilities...
  167. 📊 MCP SECURITY SCAN RESULTS
  168. ===============================
  169. 📈 Summary by Severity:
  170. 🚨 CRITICAL: 2
  171. ⚠️ HIGH: 1
  172. ⚡ MEDIUM: 3
  173. 🔍 Detailed Results:
  174. --------------------
  175. 1. 🚨 Hardcoded credentials detected
  176. 📋 ID: HARDCODED_CREDENTIALS
  177. 🎯 Severity: CRITICAL
  178. 📂 Category: credential-leak
  179. 📍 Location: src/config.ts:15
  180. 🔍 Evidence: const apiKey = "sk-***REDACTED***"
  181. ```
  182. ## Development
  183. ### Project Structure
  184. ```
  185. mcp-watch/
  186. ├── main.ts # CLI entry point
  187. ├── types/
  188. │ └── Vulnerability.ts # Type definitions
  189. ├── scanner/
  190. │ ├── MCPScanner.ts # Main scanner orchestrator
  191. │ ├── BaseScanner.ts # Base scanner utilities
  192. │ └── scanners/ # Individual vulnerability scanners
  193. │ ├── CredentialScanner.ts
  194. │ ├── ParameterInjectionScanner.ts
  195. │ └── ...
  196. ├── utils/
  197. │ └── reportFormatter.ts # Report formatting
  198. └── Docker/ # Containerization
  199. ├── Dockerfile # Production image
  200. ├── docker-compose.yml # Multi-service orchestration (Docker Compose v2)
  201. └── .dockerignore # Build optimization
  202. ```
  203. ### Development Scripts
  204. ```bash
  205. # Build the project
  206. npm run build
  207. # Run in development mode
  208. npm run dev scan https://github.com/user/repo
  209. # Quick scan during development
  210. npm run scan https://github.com/user/repo
  211. # Clean build artifacts
  212. npm run clean
  213. # Type checking
  214. npm run type-check
  215. ```
  216. ### Development Workflow 🚀
  217. #### Local Development (Recommended)
  218. ```bash
  219. # Install dependencies
  220. npm install
  221. # Run development server
  222. npm run dev
  223. # Run scans during development
  224. npm run scan https://github.com/user/repo
  225. # Type checking
  226. npm run type-check
  227. ```
  228. #### Docker Development 🐳
  229. ```bash
  230. # Build Docker image
  231. docker compose build
  232. # Test the image
  233. docker run --rm mcp-watch scan https://github.com/user/repo
  234. # Test Docker Compose
  235. docker compose run --rm mcp-watch scan --help
  236. ```
  237. ### Adding New Scanners
  238. 1. Create a new scanner in `scanner/scanners/`
  239. 2. Extend `AbstractScanner`
  240. 3. Implement the `scan()` method
  241. 4. Add to `MCPScanner.ts`
  242. Example:
  243. ```typescript
  244. import { AbstractScanner } from "../BaseScanner";
  245. import { Vulnerability } from "../../types/Vulnerability";
  246. export class MyScanner extends AbstractScanner {
  247. async scan(projectPath: string): Promise<Vulnerability[]> {
  248. console.log("🔍 Scanning for my vulnerability type...");
  249. const vulnerabilities: Vulnerability[] = [];
  250. // Your scanning logic here
  251. return vulnerabilities;
  252. }
  253. }
  254. ```
  255. ## Security Research
  256. This tool is based on security research from leading organizations in AI and cybersecurity, identifying novel attack vectors specific to MCP environments including:
  257. - **Parameter injection attacks** that extract sensitive AI context
  258. - **Tool poisoning** with hidden malicious instructions
  259. - **Conversation exfiltration** using trigger phrases
  260. - **Steganographic attacks** via ANSI escape sequences
  261. - **Toxic agent flows** across repository boundaries
  262. ### Research Sources
  263. - **VulnerableMCP Database** ([vulnerablemcp.info](https://vulnerablemcp.info))
  264. - Comprehensive database of MCP vulnerabilities
  265. - Real-world attack patterns and examples
  266. - Regular updates on new attack vectors
  267. - **HiddenLayer Research** ([Exploiting MCP Tool Parameters](https://hiddenlayer.com/innovation-hub/exploiting-mcp-tool-parameters))
  268. - Parameter injection attacks that extract sensitive data
  269. - Tool call history and conversation exfiltration
  270. - System prompt extraction vulnerabilities
  271. - Chain of thought manipulation
  272. - Model name disclosure risks
  273. - **Invariant Labs Research** ([GitHub MCP Vulnerability](https://invariantlabs.ai/blog/mcp-github-vulnerability))
  274. - Tool poisoning detection
  275. - Toxic agent flows
  276. - Cross-repository security issues
  277. - Rug-pull updates in tool functionality
  278. - Server spoofing prevention
  279. - **Trail of Bits Research** ([MCP Security Research](https://blog.trailofbits.com/categories/mcp))
  280. - Conversation exfiltration methods
  281. - ANSI injection attacks
  282. - Protocol-level vulnerabilities
  283. - Insecure credential storage patterns
  284. - Cross-server shadowing attacks
  285. - **PromptHub Analysis** ([5 MCP Security Vulnerabilities](https://prompthub.substack.com/p/5-mcp-security-vulnerabilities-you))
  286. - Command injection patterns (43% of public MCP servers affected)
  287. - SSRF vulnerability statistics (30% allow arbitrary URL fetching)
  288. - Path traversal attack vectors (22% leak files outside intended directories)
  289. - Retrieval-Agent Deception (RADE) attacks
  290. - Tool poisoning prevention strategies
  291. ## Exit Codes
  292. - `0` - No critical or high severity vulnerabilities found
  293. - `1` - Critical or high severity vulnerabilities detected
  294. - `1` - Scan error occurred
  295. ## Contributing
  296. 1. Fork the repository
  297. 2. Create a feature branch
  298. 3. Run type checking with `npm run type-check`
  299. 4. Test your changes manually
  300. 5. Submit a pull request
  301. ## GitHub Actions 🚀
  302. This repository uses automated workflows for CI/CD, security scanning, and dependency management:
  303. - **CI**: Automated testing and Docker verification on every push/PR
  304. - **Security Scan**: Daily security audits and vulnerability checks
  305. - **Release**: Automated release asset creation
  306. - **Docker Test**: Docker-specific testing and validation
  307. ## Dependabot 🤖
  308. Automated dependency management with:
  309. - **npm**: Weekly updates with auto-merge for minor/patch versions
  310. - **GitHub Actions**: Automated action updates
  311. - **Docker**: Base image updates
  312. See [GITHUB_ACTIONS.md](GITHUB_ACTIONS.md) for detailed workflow documentation.
  313. ### Docker Development Workflow 🐳
  314. ```bash
  315. # Clone and setup
  316. git clone https://github.com/kapilduraphe/mcp-watch.git
  317. cd mcp-watch
  318. # Build Docker image
  319. docker compose build
  320. # Test the image
  321. docker run --rm mcp-watch --help
  322. # Run a scan
  323. docker compose run --rm mcp-watch scan https://github.com/user/repo
  324. ```
  325. ## License
  326. MIT License - see [LICENSE](LICENSE) file for details.
  327. ## Support
  328. - Create an issue for bug reports or feature requests
  329. - Check existing issues before creating new ones
  330. - Include scan output and repository details when reporting issues
  331. ### Docker Support 🐳
  332. - **Documentation**: See [DOCKER.md](DOCKER.md) for detailed Docker usage
  333. - **Issues**: Include Docker version and Docker Compose version when reporting issues
  334. - **Testing**: Test with both production and development containers
  335. ---
  336. **⚠️ 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 in

Free to use. If it’s helped, pass it on.