GuardianMCP 🛡️
Your vigilant security companion that automatically guards your projects against vulnerabilities.
GuardianMCP is an MCP (Model Context Protocol) server that scans project dependencies for known security vulnerabilities using the OSV.dev database. Works with Cursor, VS Code, Claude Desktop, and other MCP-compatible IDEs.
Features
- Automatic vulnerability scanning for npm and Composer dependencies
- Real-time alerts for CRITICAL and HIGH severity issues
- Three scan modes: full, summary, critical-high-only
- Auto-trigger support via IDE rules (on install, commit, build)
- Multi-language keyword detection (English, Latvian, French, Spanish, German, Russian, etc.)
- Docker support for containerized deployment
- Detailed reports with remediation guidance and CVE links
- Fast & lightweight using OSV.dev API
- Secure by design - 0 vulnerabilities, minimal dependencies
Security Status
Latest security audit: All dependencies scanned, 0 vulnerabilities found Node.js: Latest LTS (22.x) with security updates Regular updates: Weekly dependency checks and monthly security reviews
See SECURITY.md for detailed security policy and audit information.
Quick Start
Choose your preferred method:
Option 1: npm (Recommended for most users)
npm install -g guardian-mcp
Option 2: From Source
git clone https://github.com/Kalvisan/guardian-mcp.git
cd guardian-mcp
npm install
npm run build
Option 3: Docker
docker pull kalmars/guardian-mcp:latest
# or
docker-compose up -d
IDE Setup Instructions
Click on your IDE to see setup instructions:
Cursor Editor (Recommended)
Cursor Setup
Cursor has native MCP support. Follow these steps:
1. Install GuardianMCP
npm install -g guardian-mcp
# or use local installation (see Quick Start)
2. Configure Cursor
Open Cursor settings:
- macOS/Linux:
~/.cursor/config.jsonorCursor Settings > Features > MCP Servers - Windows:
%APPDATA%\Cursor\config.json
Add GuardianMCP configuration:
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
Or if installed locally:
{
"mcpServers": {
"guardian-mcp": {
"command": "node",
"args": ["/absolute/path/to/guardian-mcp/dist/index.js"]
}
}
}
3. Enable Auto-Scanning (Optional)
Create .cursor/rules.md in your project:
# Security Rules
When working in this project:
- Check for CRITICAL/HIGH vulnerabilities on project start
- Scan after npm install or composer update
- Verify no critical issues before git commits
Use check_vulnerabilities tool with scan_mode="critical-high-only".
4. Restart Cursor
Completely restart Cursor to load GuardianMCP.
5. Test It
Open Cursor's AI chat and type:
Check my project for security vulnerabilities
GuardianMCP will automatically scan your dependencies!
Visual Studio Code
VS Code Setup
VS Code can use MCP servers through extensions or configuration.
Method 1: Using Continue.dev Extension
- Install Continue.dev extension
- Open Continue settings (
.continue/config.json) - Add MCP server configuration:
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
Method 2: Direct Configuration
- Install GuardianMCP:
npm install -g guardian-mcp - Add to VS Code settings (
.vscode/settings.json):
{
"mcp.servers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
3. Enable Auto-Scanning
Create .vscode/rules.md:
Automatically check for vulnerabilities when:
- Opening the project
- After running npm install/composer update
- Before creating commits
4. Restart VS Code
Reload window: Cmd/Ctrl + Shift + P → "Reload Window"
Claude Desktop
Claude Desktop Setup
Claude Desktop has built-in MCP support.
1. Install GuardianMCP
npm install -g guardian-mcp
2. Configure Claude Desktop
Open configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add GuardianMCP:
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
Or for local installation:
{
"mcpServers": {
"guardian-mcp": {
"command": "node",
"args": ["/Users/you/path/to/guardian-mcp/dist/index.js"]
}
}
}
3. Configure Auto-Scanning
Add to ~/.claude/rules.md (global) or project's .claude/rules.md:
# GuardianMCP Rules
Automatically scan for vulnerabilities when:
1. User mentions: security, vulnerability, CVE, audit
2. After package installations
3. Before git commits
Use scan_mode="critical-high-only" for auto-scans.
4. Restart Claude Desktop
Completely quit and reopen Claude Desktop.
Windsurf Editor
Windsurf Setup
Windsurf supports MCP servers similar to Cursor.
1. Install GuardianMCP
npm install -g guardian-mcp
2. Configure Windsurf
Open Windsurf configuration:
- Location:
~/.windsurf/config.json
Add MCP server:
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
3. Create Project Rules
Add .windsurf/rules.md to your project:
Auto-scan dependencies for vulnerabilities on:
- Project initialization
- npm/composer commands
- Pre-commit checks
4. Restart Windsurf
Reload the editor to activate GuardianMCP.
Zed Editor
Zed Setup
Zed is adding MCP support. Check current status:
1. Install GuardianMCP
npm install -g guardian-mcp
2. Configure Zed
Open Zed settings:
- macOS:
~/.config/zed/settings.json - Linux:
~/.config/zed/settings.json
Add configuration:
{
"assistant": {
"mcp_servers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
}
3. Restart Zed
Reload the editor.
Note: MCP support in Zed may be experimental. Check Zed documentation for latest status.
Docker Setup (Any IDE)
Docker Setup
Run GuardianMCP in a Docker container and connect from any IDE.
Method 1: Using Docker Compose (Recommended)
- Clone the repository:
git clone https://github.com/Kalvisan/guardian-mcp.git
cd guardian-mcp
- Build and run:
docker-compose up -d
- Configure your IDE:
In your IDE's MCP configuration, use:
{
"mcpServers": {
"guardian-mcp": {
"command": "docker",
"args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
}
}
}
Method 2: Docker Run
- Build the image:
docker build -t kalmars/guardian-mcp:latest .
- Run the container:
docker run -d --name guardian-mcp \
-v /path/to/your/projects:/projects:ro \
kalmars/guardian-mcp:latest
- Configure your IDE:
{
"mcpServers": {
"guardian-mcp": {
"command": "docker",
"args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
}
}
}
For Cursor with Docker:
Edit ~/.cursor/config.json:
{
"mcpServers": {
"guardian-mcp": {
"command": "docker",
"args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
}
}
}
Volume Mounting
To scan projects outside the container:
docker run -d --name guardian-mcp \
-v /Users/you/projects:/projects:ro \
-v /Users/you/work:/work:ro \
guardian-mcp:latest
Then scan with:
Scan /projects/my-app for vulnerabilities
Docker Health Check
docker ps --filter name=guardian-mcp
# Should show "healthy" status
Stopping the Container
docker-compose down
# or
docker stop guardian-mcp && docker rm guardian-mcp
Other IDEs / Custom Setup
Generic MCP Setup
For any IDE that supports Model Context Protocol:
1. Install GuardianMCP
npm install -g guardian-mcp
2. Find Your IDE's MCP Configuration
Common locations:
~/.config/[IDE_NAME]/config.json~/.config/[IDE_NAME]/settings.json~/.[IDE_NAME]/mcp.json
3. Add GuardianMCP
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
Or with full path:
{
"mcpServers": {
"guardian-mcp": {
"command": "node",
"args": ["/full/path/to/guardian-mcp/dist/index.js"]
}
}
}
4. Verify Setup
Test by asking your IDE's AI assistant:
Use the check_vulnerabilities tool to scan my project
Usage
Once GuardianMCP is installed in your IDE, you can:
Manual Scanning
Simply ask your AI assistant:
Check my project for security vulnerabilities
Scan package.json for critical issues only
Give me a full security audit
Automatic Scanning
Configure rules in your IDE's rules file (.cursor/rules.md, .claude/rules.md, etc.):
# Security Automation
When I mention: security, vulnerability, CVE, audit, or exploit
→ Run check_vulnerabilities with scan_mode="critical-high-only"
After running: npm install, npm update, composer install, composer update
→ Automatically scan for new vulnerabilities
Before creating git commits:
→ Check for CRITICAL vulnerabilities and warn if found
Tool Parameters
GuardianMCP provides the check_vulnerabilities tool with these parameters:
| Parameter | Type | Options | Default | Description |
|---|---|---|---|---|
project_path | string | any path | current dir | Path to project directory |
file_type | string | package.json, composer.json, both | both | Which files to scan |
scan_mode | string | full, summary, critical-high-only | full | Output detail level |
Examples
Full scan:
Check vulnerabilities with scan_mode="full"
Quick summary:
How many vulnerabilities are in my project? (uses scan_mode="summary")
Auto-scan mode (recommended):
Scan for critical vulnerabilities only (scan_mode="critical-high-only")
Scan Modes Explained
full Mode
Best for: Manual security audits, comprehensive reviews
Shows ALL vulnerabilities with complete details:
- CRITICAL, HIGH, MODERATE, and LOW severity
- Detailed descriptions and remediation steps
- Reference links and CVE IDs
- Update commands for each package
Example output:
## 🔴 express@4.17.1
**Vulnerability ID:** GHSA-rv95-896h-c2vc
**Severity:** CRITICAL
### ⚠️ CRITICAL RISK!
**Description:** Express.js accepts requests with malformed URL encoding
**IMMEDIATE ACTION REQUIRED:**
1. Update package: npm update express
2. Verify no vulnerable functionality is used
...
summary Mode
Best for: Quick health checks, CI/CD dashboards
Shows only vulnerability counts:
- Fast overview
- No detailed descriptions
- Total counts by severity
Example output:
## 📊 Summary
- 🔴 Critical: 2
- 🟠 High: 5
- 🟡 Moderate: 12
- 🟢 Low: 3
**Total: 22 vulnerabilities**
Run with scan_mode="full" for details.
critical-high-only Mode
Best for: Auto-scans, automated monitoring (RECOMMENDED for rules)
Shows detailed info for CRITICAL/HIGH, counts others:
- Reduces noise
- Highlights actionable issues
- Perfect for automatic scans
- Hides moderate/low details
Example output:
## 🔴 lodash@4.17.20
**Severity:** HIGH
**Issue:** Prototype pollution vulnerability
**Recommendation:** npm update lodash
---
## 📊 Summary
- 🔴 Critical: 1
- 🟠 High: 2
_Also found 8 moderate/low issues (hidden)._
_Run with scan_mode="full" to see all._
Severity Levels
| Level | Icon | Action | Examples |
|---|---|---|---|
| CRITICAL | 🔴 | Update IMMEDIATELY | RCE, Auth bypass, Privilege escalation |
| HIGH | 🟠 | Update ASAP | SQL injection, XSS, CSRF |
| MODERATE | 🟡 | Plan update | DoS, Information disclosure |
| LOW | 🟢 | Consider updating | Deprecated packages, Minor issues |
Example Rules Files
See examples/ for ready-to-use templates:
claude-rules.md- Comprehensive template with all scenariosproject-rules.md- Project-specific configuration exampleglobal-rules.md- User-wide configuration for all projects
Copy these to:
- Cursor:
.cursor/rules.md - Claude Desktop:
.claude/rules.md - VS Code:
.vscode/rules.md(with Continue.dev)
Supported Ecosystems
| Ecosystem | File | Status |
|---|---|---|
| npm (Node.js) | package.json | ✅ Supported |
| Composer (PHP) | composer.json | ✅ Supported |
| PyPI (Python) | requirements.txt | 🔄 Planned |
| Go Modules | go.mod | 🔄 Planned |
| Maven (Java) | pom.xml | 🔄 Planned |
| NuGet (.NET) | *.csproj | 🔄 Planned |
| RubyGems | Gemfile | 🔄 Planned |
| Cargo (Rust) | Cargo.toml | 🔄 Planned |
Troubleshooting
GuardianMCP not showing up in IDE
-
Verify installation:
npx guardian-mcp --version # or which guardian-mcp -
Check config file path is absolute:
- ❌
"args": ["dist/index.js"] - ✅
"args": ["/Users/you/guardian-mcp/dist/index.js"]
- ❌
-
Restart IDE completely (don't just reload window)
-
Check IDE logs:
- Cursor: Open DevTools (Help > Toggle Developer Tools)
- VS Code: Output panel > Extension Host
- Claude Desktop: View > Developer > Toggle Developer Tools
-
Test manually:
node /path/to/guardian-mcp/dist/index.js # Should not crash
Auto-scanning not working
-
Verify rules file exists:
cat .cursor/rules.md # or cat .claude/rules.md -
Check rules mention tool name:
- Must reference
check_vulnerabilities - Use
scan_mode="critical-high-only"for auto-scans
- Must reference
-
Test with keywords:
- Try saying "security" or "vulnerability"
- Should trigger automatic scan
-
Check IDE supports rules:
- Cursor: ✅ Built-in support
- Claude Desktop: ✅ Built-in support
- VS Code: Depends on extension
Docker container not starting
-
Check logs:
docker logs guardian-mcp -
Verify build succeeded:
docker build -t kalmars/guardian-mcp:latest . -
Test manually:
docker run -it kalmars/guardian-mcp:latest -
Check health:
docker ps --filter name=guardian-mcp # Status should be "healthy"
OSV.dev API errors
-
Check internet connection
-
Verify API is accessible:
curl https://api.osv.dev/v1/query -
Rate limiting: OSV.dev has rate limits
- Wait a few minutes
- Reduce scan frequency
-
Firewall: Ensure outbound HTTPS is allowed
Contributing
Contributions are welcome! Areas for improvement:
- Additional ecosystem support (Python, Go, Rust, etc.)
- Better version range parsing
- Caching to reduce API calls
- IDE-specific optimizations
- Test coverage
- Documentation improvements
License
MIT - See LICENSE file
Resources
- OSV.dev Database
- OSV.dev API Docs
- Model Context Protocol
- MCP TypeScript SDK
- Cursor Documentation
- VS Code MCP Guide
Security Note
GuardianMCP helps identify known vulnerabilities but is not a substitute for:
- Comprehensive security audits
- Penetration testing
- Secure coding practices
- Regular dependency updates
- Security training
Always review and test dependency updates before deploying to production.
Made with 🛡️ by the GuardianMCP team