GuardianMCP: Automated Scan Server for Project Dependency Vulnerabilities, Supports npm & Composer, Integrates with IDE

Guardian MCP

GuardianMCP is an MCP server that automatically scans for security vulnerabilities in project dependencies. It supports npm and Composer, provides real-time alerts and multiple scanning modes, and can be integrated with mainstream IDEs.

Security Developer tools #Security scanning #Dependency vulnerabilities #IDE integration #Real-time monitoring .TypeScript

rating : 2 points

downloads : 7.0K

update time : 2025-12-03

Open Site

What is GuardianMCP?

GuardianMCP is a security scanning server based on the Model Context Protocol (MCP), specifically designed to detect known security vulnerabilities in project dependency packages. It connects to the OSV.dev vulnerability database, automatically analyzes your npm and Composer dependencies, and provides real-time security alerts and repair suggestions.

How to use GuardianMCP?

GuardianMCP can be integrated into your favorite IDE (such as Cursor, VS Code, Claude Desktop, etc.). After installation, you can perform security scans through simple dialogue commands. It supports automatic trigger scans and can also perform manual security checks when you need them.

Use cases

GuardianMCP is particularly suitable for the following scenarios: 1. Security check at project startup 2. Vulnerability verification after installing new dependency packages 3. Security review before code submission 4. Regular project security audit 5. Automatic security check in the CI/CD pipeline

Main features

Automatic vulnerability scanning

Automatically detect known security vulnerabilities in npm and Composer dependencies without manual configuration of scanning rules.

Real-time security alerts

Immediately detect severe vulnerabilities of CRITICAL and HIGH levels and provide detailed repair guidance.

Three scanning modes

Supports full scan, summary mode, and critical vulnerability-only scan to meet the needs of different scenarios.

Automatic trigger support

Can automatically perform scans based on IDE rules at specific events (such as installing dependencies, submitting code).

Multi-language keyword detection

Supports the recognition of security-related keywords in multiple languages such as English, Latvian, French, Spanish, German, and Russian.

Docker containerization support

Provides Docker images and docker-compose configurations for easy deployment and use in container environments.

Detailed reports and repair guidance

Provides a complete report containing CVE links, severity assessments, and specific repair steps.

Fast and lightweight scan

Based on the OSV.dev API, the scanning speed is fast, the resource usage is low, and it does not affect the development workflow.

Advantages

Zero-vulnerability design: It has no security vulnerabilities itself, and the dependency packages are kept up-to-date.

Easy to integrate: Supports mainstream IDEs and is easy to configure.

Real-time updates: Based on the OSV.dev database, the vulnerability information is up-to-date.

High degree of automation: Supports rule triggering, reducing manual operations.

Multi-language support: Recognizes security-related keywords in multiple languages.

Containerized deployment: Provides Docker support for flexible deployment.

Limitations

Currently only supports the npm and Composer ecosystems.

Relies on the OSV.dev API and requires an internet connection.

Cannot detect vulnerabilities in custom code.

Requires the IDE to support the MCP protocol.

Advanced features require certain configuration knowledge.

How to use

Install GuardianMCP

Choose the installation method that suits you: global installation, source code installation, or Docker installation.

Configure the IDE

According to the IDE you are using (Cursor, VS Code, Claude Desktop, etc.), add the MCP server settings to the configuration file.

Set up automatic scanning rules (optional)

Create a rules file in the project directory to define when to automatically trigger security scans.

Restart the IDE and test

Completely restart your IDE, and then enter security-related commands in the AI chat for testing.

Usage examples

New project security check

When starting a new project, quickly check the security of all dependency packages.

Verification after installing dependencies

After running npm install or composer update, automatically verify if the newly installed packages are secure.

Review before code submission

Before submitting code to the version control system, perform a final security check.

Regular security audit

Regularly conduct a comprehensive security audit of the project to understand the overall security situation.

Frequently Asked Questions

Which programming languages does GuardianMCP support?

Does GuardianMCP require an internet connection?

Will the scan affect my development performance?

How to configure automatic scanning?

Can GuardianMCP detect vulnerabilities in custom code?

How is the severity in the scan results divided?

What should I do if a vulnerability is found?

Is GuardianMCP itself secure?

Related resources

GitHub repository

The source code and latest version of GuardianMCP

OSV.dev vulnerability database

The vulnerability data source used by GuardianMCP

Model Context Protocol official website

The official documentation and specifications of the MCP protocol

Cursor editor

An AI code editor that supports MCP

Claude Desktop

An AI assistant desktop application that supports MCP

Example configuration files

Configuration examples and rule templates for various IDEs

🚀 GuardianMCP 🛡️

GuardianMCP is your vigilant security companion that automatically guards your projects against vulnerabilities. It's an MCP (Model Context Protocol) server that scans project dependencies for known security vulnerabilities using the OSV.dev database. This tool works seamlessly with Cursor, VS Code, Claude Desktop, and other MCP-compatible IDEs.

✨ Features

Automatic vulnerability scanning: Conducts scans on npm and Composer dependencies.
Real-time alerts: Provides instant notifications for CRITICAL and HIGH severity issues.
Three scan modes: Offers full, summary, and critical-high-only scan modes.
Auto-trigger support: Can be auto-triggered via IDE rules (on install, commit, build).
Multi-language keyword detection: Supports multiple languages, including English, Latvian, French, Spanish, German, Russian, etc.
Docker support: Enables containerized deployment.
Detailed reports: Generates reports with remediation guidance and CVE links.
Fast & lightweight: Utilizes the OSV.dev API for efficient operations.
Secure by design: Boasts 0 vulnerabilities and minimal dependencies.

📊 Security Status

Latest security audit: All dependencies scanned, 0 vulnerabilities found.
Node.js: Runs on the latest LTS (22.x) with security updates.
Regular updates: Performs weekly dependency checks and monthly security reviews.

See SECURITY.md for detailed security policy and audit information.

🚀 Quick Start

Choose your preferred installation 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.json or Cursor 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 for ready-to-use templates:

claude-rules.md - Comprehensive template with all scenarios
project-rules.md - Project-specific configuration example
global-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
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