convez.ai
MCP Server
napatmanasilp

mcpguardian

napatmanasilp/mcpguardian

Ver no GitHub
InicialPluginScore · de 0 a 100

Security guardrails, policy enforcement, and runtime protection for Model Context Protocol (MCP) servers and AI agents.

Instalação

$npx convez-ai napatmanasilp/mcpguardian

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.


What It Detects

MCPGuardian scans MCP server configurations and runtime behavior across 36 issue types organized into 9 categories. Each issue is mapped to the OWASP MCP Top 10 security framework.

CategoryIssues DetectedMax SeverityOWASP MCP
Credential & Secret ExposureHardcoded secrets, env var exposure, credential reflection, hardcoded argsCRITICALMCP01
Supply Chain & ProvenanceVulnerable packages, typosquatting, slopsquatting, unpinned deps, unverified sources, prerelease packagesCRITICALMCP04
Permission & FilesystemBroad permissions, root FS access, unrestricted FS, file system resources, internal resource exposureCRITICALMCP02
Tool Poisoning & InjectionTool/prompt/resource poisoning, hidden instruction tags, homoglyph attacksCRITICALMCP03, MCP06
Execution & TransportSTDIO transport, unsafe commands, command execution, consent bypassCRITICALMCP05, MCP08
Authentication & NetworkMissing auth, weak Basic/Digest, no PKCE, no token expiry, insecure URL, legacy SSEHIGHMCP07
Cross-Server & IntegrityRug-pull detection, tool shadowing, cross-server manipulation, compound riskCRITICALMCP09
DocumentationUndocumented prompts, resource metadataLOWMCP10
InformationalProbe failed, SBOM unavailableLOW—

Quick Start

Scan via Web UI

Visit https://mcpguardian.dev/scan — paste your MCP config JSON and get an instant security report with grade, score, and detailed issue breakdown.

Scan via REST API

curl -X POST https://mcpguardian.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"config": {"mcpServers": {"my-server": {"url": "https://example.com/mcp"}}}}'

Returns a ScanResult with grade (A–F), score, per-server issues, cross-server risk analysis, SBOM, and compliance summary.

Use as MCP Tool (Claude Desktop / Cursor)

Add to your MCP client config:

{
  "mcpServers": {
    "mcpguardian": {
      "url": "https://mcpguardian.dev/api/mcp-server",
      "transport": "http"
    }
  }
}

Available tools:

ToolDescription
scan_mcp_configScan an MCP config JSON and return a full security report
check_mcp_serverLive-probe an MCP server URL for runtime vulnerabilities
lookup_cveLook up CVE details for a known MCP package
verify_tool_definitionCompare current tool definitions against a historical snapshot
get_scan_historyRetrieve recent scan results for your account

Use as Proxy Gateway

Point your MCP client at MCPGuardian's proxy instead of connecting to your MCP server directly:

POST https://mcpguardian.dev/api/proxy?upstream=<YOUR_MCP_SERVER_URL>

Optional header: X-MCPGuardian-Mode: monitor | block | off

  • monitor (default) — logs all findings, never blocks
  • block — blocks SSRF attempts and injection payloads with HTTP 403, sanitizes poisoned responses
  • off — bypasses all inspection, zero overhead forwarding

The proxy appends _mcpguardian metadata to every response with mode, flags raised, session ID, and latency timing.


Database Schema

MCPGuardian uses PostgreSQL (via Supabase) with the following tables:

profiles

User profiles linked to Supabase Auth.

ColumnTypePurpose
iduuid PKReferences auth.users
emailtextUser email
plantextSubscription plan (free / pro)
stripe_customer_idtextStripe customer ID for billing
scans_this_monthintegerScans used in current billing period
max_scansintegerMonthly scan limit
created_attimestamptzAccount creation timestamp

scans

Scan results for a user's MCP config.

ColumnTypePurpose
iduuid PKAuto-generated
user_iduuid FKReferences profiles.id
overall_gradechar(1)A–F grade
overall_scoreintegerNumeric score (0–100)
servers_scannedintegerNumber of MCP servers evaluated
critical_issuesintegerCount of critical-severity issues
high_issuesintegerCount of high-severity issues
resultsjsonbFull scan result payload
created_attimestamptzScan timestamp

monitored_configs

MCP configurations under continuous monitoring.

ColumnTypePurpose
iduuid PKAuto-generated
user_iduuid FKReferences profiles.id
nametextHuman-readable label
config_jsonjsonbMCP server configuration
last_scan_iduuid FKReferences most recent scans.id
last_scoreintegerScore from most recent scan
scan_frequencytextCron-like schedule (daily, hourly)
is_activebooleanWhether monitoring is enabled
created_attimestamptzCreation timestamp

alerts

Security alerts generated from scans or monitoring.

ColumnTypePurpose
iduuid PKAuto-generated
user_iduuid FKReferences profiles.id
monitored_config_iduuid FKReferences monitored_configs.id
alert_typetextIssue type (e.g. VULNERABLE_PACKAGE)
severitytextCRITICAL / HIGH / MEDIUM / LOW
titletextAlert headline
messagetextDetailed description
issue_keytextDedup key (unique per active alert)
recurrence_countintegerTimes this alert has recurred
readbooleanUser read status
resolved_attimestamptzWhen the issue was resolved
created_attimestamptzAlert creation timestamp
updated_attimestamptzLast update timestamp

mcp_cves

Known CVE database for MCP ecosystem packages.

ColumnTypePurpose
iduuid PKAuto-generated
cve_idtextCVE identifier or N/A
package_nametext UNIQUEPackage name
affected_versionstextSemver range or description
fixed_versiontextPatched version
severitytextCRITICAL / HIGH / MEDIUM
descriptiontextVulnerability description
fixtextRemediation instructions
match_typetextexact or substring
version_fieldtextsemver, all, or flag-check
is_activebooleanWhether this entry is active
published_attimestamptzOriginal publish date
created_attimestamptzCreated timestamp
updated_attimestamptzUpdated timestamp

tool_definition_snapshots

Historical snapshots of server tool definitions for rug-pull detection.

ColumnTypePurpose
idbigint PKAuto-generated identity
config_hashtextHash of MCP config
server_urltextMCP server URL
tools_hashtextSHA-256 hash of tool definitions
tools_snapshotjsonbFull tool definitions
first_seen_attimestamptzFirst observation
last_seen_attimestamptzMost recent observation
change_countintegerNumber of tool changes detected

Environment Variables

VariableRequiredDescription
NEXT_PUBLIC_SUPABASE_URLYesSupabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEYYesSupabase anonymous/public key
SUPABASE_SERVICE_ROLE_KEYYesSupabase service role key (admin)
CRON_SECRETYesShared secret for cron job authentication
NVD_API_KEYNoNVD API key for CVE sync (optional, rate-limited without)
RESEND_API_KEYNoResend API key for transactional email
POLAR_WEBHOOK_SECRETNoPolar webhook signing secret
NEXT_PUBLIC_SITE_URLNoPublic site URL (defaults to localhost:3000)

Compliance

MCPGuardian maps every detected issue to the OWASP MCP Top 10, OWASP Agentic Security, and NSA CSI frameworks. The compliance summary returned with each scan includes all framework categories that were triggered.

OWASP MCP Top 10 Coverage

IDCategoryCoverageDetection Examples
MCP01Credential & Secret Exposure✅ FullHardcoded secrets, env exposure, credential reflection
MCP02Permission & Filesystem✅ FullBroad FS perms, root access, internal resource exposure
MCP03Tool Poisoning & Injection✅ FullHidden instruction tags, homoglyph attacks, prompt/resource poisoning
MCP04Software Supply Chain Attacks✅ FullVulnerable packages, typosquatting, slopsquatting, unpinned deps
MCP05Execution & Transport✅ FullSTDIO transport, unsafe commands, command injection
MCP06Tool Poisoning (Extended)✅ FullTool/prompt/resource poisoning detection
MCP07Authentication & Network✅ FullMissing auth, weak auth schemes, insecure URLs, legacy SSE
MCP08User Consent & Awareness✅ FullConsent bypass detection
MCP09Cross-Server Integrity✅ FullRug-pull detection, tool shadowing, cross-server manipulation
MCP10Documentation & Transparency✅ FullUndocumented prompts, probe metadata

Performance

Latency benchmarks (measured via tests/proxy-latency.bench.ts, 100 iterations each):

Scenariop50p95p99Max
Proxy overhead (inspection only)< 1ms< 2ms< 5ms< 10ms
Full round trip (mock upstream)< 10ms< 50ms< 100ms< 200ms
Block mode with SSRF rejection< 1ms< 2ms< 5ms< 10ms

Ver o original no GitHub

Relacionados