Skip to main content
Glama

GuardianMCP

by Kalvisan
OverviewInspectNewSchemaRelated ServersScore
JavaScript
Hybrid
MIT License
1
  • Apple
  • Linux

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

npm audit Node.js Dependencies

✅ 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 our security policy and audit details.

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 guardian-mcp:latest # or docker-compose up -d

IDE Setup Instructions

Click on your IDE to see setup instructions:

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!

VS Code Setup

VS Code can use MCP servers through extensions or configuration.

Method 1: Using Continue.dev Extension

  1. Install Continue.dev extension

  2. Open Continue settings (.continue/config.json)

  3. Add MCP server configuration:

{ "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

Method 2: Direct Configuration

  1. Install GuardianMCP: npm install -g guardian-mcp

  2. 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 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 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 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

Run GuardianMCP in a Docker container and connect from any IDE.

Method 1: Using Docker Compose (Recommended)

  1. Clone the repository:

git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp

  1. Build and run:

docker-compose up -d

  1. 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

  1. Build the image:

docker build -t guardian-mcp:latest .

  1. Run the container:

docker run -d --name guardian-mcp \ -v /path/to/your/projects:/projects:ro \ guardian-mcp:latest

  1. 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

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 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

  1. Verify installation:

    npx guardian-mcp --version # or which guardian-mcp

  2. Check config file path is absolute:

    • ❌ "args": ["dist/index.js"]

    • ✅ "args": ["/Users/you/guardian-mcp/dist/index.js"]

  3. Restart IDE completely (don't just reload window)

  4. Check IDE logs:

    • Cursor: Open DevTools (Help > Toggle Developer Tools)

    • VS Code: Output panel > Extension Host

    • Claude Desktop: View > Developer > Toggle Developer Tools

  5. Test manually:

    node /path/to/guardian-mcp/dist/index.js # Should not crash

  1. Verify rules file exists:

    cat .cursor/rules.md # or cat .claude/rules.md

  2. Check rules mention tool name:

    • Must reference check_vulnerabilities

    • Use scan_mode="critical-high-only" for auto-scans

  3. Test with keywords:

    • Try saying "security" or "vulnerability"

    • Should trigger automatic scan

  4. Check IDE supports rules:

    • Cursor: ✅ Built-in support

    • Claude Desktop: ✅ Built-in support

    • VS Code: Depends on extension

  1. Check logs:

    docker logs guardian-mcp

  2. Verify build succeeded:

    docker build -t guardian-mcp:latest .

  3. Test manually:

    docker run -it guardian-mcp:latest

  4. Check health:

    docker ps --filter name=guardian-mcp # Status should be "healthy"

  1. Check internet connection

  2. Verify API is accessible:

    curl https://api.osv.dev/v1/query

  3. Rate limiting: OSV.dev has rate limits

    • Wait a few minutes

    • Reduce scan frequency

  4. Firewall: Ensure outbound HTTPS is allowed

Development

Local Development

git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp npm install npm run watch # Auto-recompile on changes

Testing Changes

npm run build node dist/index.js # Test locally

Adding New Ecosystems

  1. Create checkXXXJson() function in src/index.ts

  2. Follow pattern of checkPackageJson() or checkComposerJson()

  3. Update file_type enum and descriptions

  4. Use appropriate OSV.dev ecosystem name

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

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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Related Resources

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Kalvisan/guardian-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server