🛡️ VibeDefender
Security Knowledge MCP Server for AI Coding Agents
Guide your AI agents through professional security assessments with methodology, documentation, and step-by-step workflows covering OWASP Top 10 and beyond.
Installation • Features • Quick Start • Configuration • Documentation
🌟 Why VibeDefender?
Your AI coding agent (Claude Code, Cursor, etc.) already knows how to run commands. VibeDefender teaches it WHEN, WHY, and HOW to run security tools like a professional pentester.
Instead of guessing which security tools to run, your AI gets:
- 📚 Step-by-step security methodology - Professional assessment workflows
- 🎯 Plain English guidance - No security expertise required
- 🔧 Tool installation guides - Automated setup assistance
- 📖 Always-current documentation - Live tool documentation proxy
- ✅ OWASP Top 10 coverage - Industry-standard vulnerability detection
⭐ If you find VibeDefender useful, please star this repo! It helps others discover professional security testing for AI agents.
📦 Installation
Direct from GitHub (Recommended)
npx github:yunusj/VibeDefender-MCP
This automatically clones, installs dependencies, builds, and runs the MCP server.
Global Installation
npm install -g github:yunusj/VibeDefender-MCP
vibedefender-mcp
✨ Features
🎯 What Makes VibeDefender Different
✅ Knowledge-First Approach - Guides AI agents instead of executing tools directly ✅ 5 Pre-Built Security Workflows - Setup, full scan, pre-push check, live testing, URL scanning ✅ OWASP Top 10 Coverage - Comprehensive vulnerability detection (injection, XSS, auth, etc.) ✅ Mandatory Runtime Analysis - Not just static analysis - tests your running application ✅ Artifact Generation - Saves all scan results as JSON + markdown reports ✅ Zero Security Knowledge Required - Plain English explanations for non-security developers ✅ Tool Agnostic - Works with any MCP-compatible AI editor (Claude Code, Cursor, etc.)
🔧 Integrated Security Tools
- Trivy - CVE and dependency vulnerability scanning
- Semgrep - Static code analysis with 2000+ security rules
- Nuclei - Runtime security testing with template-based scanning
- Metasploit - Optional integration for discovery and exploitation
🤖 Supported AI Editors
| Editor | Status | Notes |
|---|---|---|
| Claude Code | ✅ Fully Supported | Native MCP support |
| Cursor | ✅ Fully Supported | MCP configuration required |
| Claude Desktop | ✅ Fully Supported | Config in claude_desktop_config.json |
| Google Antigravity | ✅ Fully Supported | Same config as Claude Desktop |
🧠 Philosophy
The MCP GUIDES, not executes.
Your AI agent (Claude Code, Cursor, etc.) already has the ability to run CLI commands. This MCP provides:
- 📋 Step-by-step methodology for security assessments
- 🔧 Installation guides for required tools
- 💬 Plain English explanations for non-technical users
- 📚 Documentation proxy for always-current tool docs
⚡ Quick Start
- Install and configure (one-time setup):
{
"mcpServers": {
"vibedefender": {
"command": "npx",
"args": ["github:yunusj/VibeDefender-MCP"]
}
}
}
- Talk to your AI agent in plain English:
| What You Say | What Happens |
|---|---|
| 💬 "Help me set up security scanning" | 🔧 AI installs Trivy, Semgrep, Nuclei with guided steps |
| 💬 "Scan my code for security issues" | 🔍 Full scan: dependencies + code + runtime + artifacts |
| 💬 "Check my code before I push" | ⚡ Fast critical-only check (< 30 seconds) |
| 💬 "Test my app on localhost" | 🌐 Starts dev server + runs live security tests |
| 💬 "Check this URL for vulnerabilities" | 🎯 Tests specific URL with authorization check |
- Get professional security reports with actionable fixes:
✅ All scans saved to: security-scan-20241220-143022/
├── trivy-results.json (Dependency vulnerabilities)
├── semgrep-results.json (Code security issues)
├── nuclei-results.json (Runtime vulnerabilities)
└── REPORT.md (Human-readable summary)
⚙️ Configuration
Claude Code
Add to your Claude Code MCP settings:
{
"mcpServers": {
"vibedefender": {
"command": "npx",
"args": ["github:yunusj/VibeDefender-MCP"]
}
}
}
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"vibedefender": {
"command": "npx",
"args": ["github:yunusj/VibeDefender-MCP"]
}
}
}
Cursor
Add to Cursor's MCP settings (Settings → Features → MCP):
{
"mcpServers": {
"vibedefender": {
"command": "npx",
"args": ["github:yunusj/VibeDefender-MCP"]
}
}
}
Google Antigravity
Same configuration as Claude Desktop.
🧪 Testing with MCP Inspector
Test the server before configuring in your editor:
npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector npx github:yunusj/VibeDefender-MCP
Expected: Web UI shows "Connected", lists all security:// resources and 5 workflow prompts.
🎯 Available Workflows
| Workflow | Trigger Phrase | What It Does |
|---|---|---|
🔧 setup | "Help me set up security scanning" | Checks installed tools, guides installation |
🔍 scan | "Scan my code for security issues" | Full scan: static + runtime + artifacts |
⚡ pre-push | "Check my code before I push" | Fast check: critical issues only (< 30s) |
🌐 scan-live | "Test my app on localhost" | Starts dev server + runs live tests |
🎯 scan-url | "Check this URL for vulnerabilities" | Tests specific URL (requires authorization) |
🛠️ Required Tools
The MCP guides you through installing these (just say "help me set up"):
| Tool | Purpose | Install (macOS) |
|---|---|---|
| 🔍 Trivy | CVE/dependency scanning | brew install aquasecurity/trivy/trivy |
| 📝 Semgrep | Static code analysis | brew install semgrep |
| 🌐 Nuclei | Runtime testing (mandatory) | brew install nuclei |
🎖️ Metasploit Integration
Metasploit Framework is integrated for both discovery (reconnaissance) and exploitation phases.
Setup
- Install external Metasploit MCP server:
# Clone the Metasploit MCP repository
git clone https://github.com/your-org/MetasploitMCP ~/MetasploitMCP
- Set environment variable (add to
~/.bashrcor~/.zshrc):
export METASPLOIT_MCP_PATH="$HOME/MetasploitMCP/start_mcp.sh"
- Verify installation:
npm run mcp:metasploit
# Should output: "Metasploit MCP Proxy running on stdio"
Usage
Discovery Phase (Automatic):
- Runs safe auxiliary modules for service detection
- Port scanning and version detection
- Correlates findings with CVE database
- No exploitation attempts
Exploitation Phase (Requires Approval):
- Executes exploits against validated vulnerabilities
- Requires explicit human approval
- Full session management and post-exploitation
- Evidence gathering only (read-only)
Safety
⚠️ CRITICAL: Authorization Required
- Only use on systems you own OR have written permission to test
- Unauthorized access to computer systems is illegal
- Discovery phase: Basic authorization sufficient
- Exploitation phase: Explicit approval required
📖 Documentation
- See
security://methodology/exploitationfor complete exploitation workflow - See
security://docs/metasploitfor detailed tool usage - Includes safety guidelines, workflow examples, and troubleshooting
📚 Available Resources
📋 Methodology Guides
| Resource | Description |
|---|---|
security://methodology/discovery | 🔍 How to find attack surface |
security://methodology/scanning | 📊 What to scan, in what order |
security://methodology/validation | ✅ How to validate on live targets |
security://methodology/reporting | 📝 How to structure reports |
📖 Reference Documentation
| Resource | Description |
|---|---|
security://reference/severity | 🚨 What CRITICAL/HIGH/MEDIUM/LOW mean |
security://reference/cwe-top-25 | 🐛 Common weakness types |
security://reference/owasp-top-10 | 🛡️ OWASP vulnerability categories |
security://reference/browser-options | 🌐 Browser automation choices |
🔧 Tool Documentation
| Resource | Description |
|---|---|
security://docs/overview | 📚 Overview of all tools |
security://docs/trivy | 🔍 Trivy quick start |
security://docs/semgrep | 📝 Semgrep quick start |
security://docs/nuclei | 🌐 Nuclei quick start |
security://docs/playwright | 🎭 Playwright MCP info |
security://docs/metasploit | 🎖️ Metasploit basics |
💡 Example Workflows
First Time Setup
You: Help me set up security scanning
AI: I'll check what tools you have installed...
[Runs version checks]
You're missing Trivy and Semgrep. Let me help you install them.
Trivy checks your dependencies for known vulnerabilities.
Run this to install: brew install aquasecurity/trivy/trivy
...
Before Pushing Code
You: Check my code before I push
AI: Running quick pre-push security check...
[Runs trivy + semgrep for CRITICAL issues only]
✅ All clear! No critical security issues found. Safe to push.
For a comprehensive scan including runtime testing, use the 'scan' workflow.
Full Security Scan
You: Scan my code for security issues
AI: I see this is a Node.js project using Express.
First, checking for known vulnerabilities in dependencies...
[Runs trivy]
Found 3 critical issues in your packages:
1. lodash < 4.17.21 - allows prototype pollution
Fix: npm update lodash
...
📁 Project Structure
src/
├── index.ts # Main MCP server entry point
├── resources/
│ ├── static.ts # Bundled methodology & references
│ └── dynamic.ts # Tool documentation with search guidance
└── prompts/
└── workflows.ts # 5 user-friendly workflow prompts
🎨 Design Decisions
- 🚫 No execution tools - AI agents already have CLI access. We provide knowledge.
- 💬 Plain English - Everything explained for non-technical users.
- 📋 Step-by-step - Prompts tell the AI exactly what to do at each step.
- 📖 Documentation proxy - Search patterns for always-current tool docs.
- 📦 Minimal files - 4 files total, easy to understand and maintain.
- 🌐 GitHub-based distribution - No npm publish, direct from source via npx.
🌐 Browser Automation Options
For live testing that needs a browser:
| Option | When to Use |
|---|---|
| Playwright MCP | Claude Code, Cursor, most IDEs |
| Browser Agent | Google Antigravity IDE (built-in) |
| Puppeteer | If already in project |
🔧 Troubleshooting
Build Errors
If you see TypeScript compilation errors when installing from GitHub:
npm cache clean --force
npx github:yunusj/VibeDefender-MCP
MCP Server Not Connecting
- Test with MCP Inspector first (see "Testing" section above)
- Check Node.js version:
node --version(requires >= 22.0.0) - Verify the server runs standalone:
npx github:yunusj/VibeDefender-MCP # Should output: "Security Knowledge MCP server running on stdio" - Check editor configuration file syntax (valid JSON)
- Restart your AI editor after configuration changes
Permission Errors
If you get EACCES errors:
# On Unix-like systems, the shebang should make it executable
# If not, manually set permissions on global install:
chmod +x $(which vibedefender-mcp)
Update to Latest Version
npm cache clean --force
npx github:yunusj/VibeDefender-MCP
# Or for global install
npm uninstall -g vibedefender-mcp
npm install -g github:yunusj/VibeDefender-MCP
⚠️ Security Notice
- ✅ Only scan systems you are authorized to test
- 🔒 Live validation (scan-url, scan-live) requires explicit authorization
- 🤝 The AI will ask for confirmation before testing URLs
- 📄 Always get written permission before security testing
- 🛡️ Follow responsible disclosure practices
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
MIT License - see LICENSE for details
⭐ Show Your Support
If VibeDefender helps secure your code, please star this repository!
Made with 🛡️ by security professionals, for developers