MCPShield Agent

AI Agent Security Scanner - Discovers MCP servers on your system and reports them to MCPShield for security analysis.

Installation

# Install from PyPI
pip install mcpshield-agent

# Or install from source
pip install -e .

Quick Start

# Scan your machine and see a local risk score. No account needed.
pip install mcpshield-agent
mcpshield scan

mcpshield scan discovers your MCP servers and prints a 0-100 risk score for each, computed locally. Sign up (free) and configure --api-key to add CISA KEV enrichment, org-wide tracking, history, and alerts:

mcpshield configure --api-key mcp_sk_your_key_here
mcpshield scan     # now also reports to the dashboard
mcpshield status

Embed the scorer

The risk scorer is a pure function you can drop into any runtime to score an MCP server config in three lines:

from mcpshield_agent import score_config, risk_level

result = score_config({
    "server_type": "@modelcontextprotocol/server-filesystem",
    "command": "npx -y @modelcontextprotocol/server-filesystem /",
    "scope": "/",
    "env_vars": ["AWS_SECRET_ACCESS_KEY"],
})
# {"score": 100.0, "level": "critical", "factors": [...], "details": {...}}

It is the same weighted model as the hosted engine (minus CISA KEV enrichment, which stays server-side) and has no network dependency.

Risk-oracle MCP server

Expose the same scorer as an MCP server, so any MCP-capable agent (a SOC agent, Claude Desktop, Cursor) can consult MCPShield as a risk authority before it trusts or invokes an MCP server:

pip install 'mcpshield-agent[mcp]'   # needs Python 3.10+
mcpshield-mcp                         # runs as a stdio MCP server

Register it with any MCP client, e.g. an mcp_servers.json entry:

{ "name": "mcpshield", "command": "mcpshield-mcp" }

Tools it exposes:

Each returns a 0-100 risk_score, a risk_level, and the risk_factors behind it. Scoring is local and deterministic, and credential values are never returned — only the credential type appears in the factors, and an inline credential in a URL-style scope is masked.

Commands

What It Scans

The agent looks for MCP server configurations in:

Windows:

• %APPDATA%\Claude\claude_desktop_config.json
• %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• %APPDATA%\Windsurf\mcp_settings.json
• %APPDATA%\Zed\settings.json

macOS:

• ~/Library/Application Support/Claude/claude_desktop_config.json
• ~/.cursor/mcp.json
• ~/.config/zed/settings.json
• ~/.continue/config.json

Linux:

• ~/.config/Claude/claude_desktop_config.json
• ~/.config/cursor/mcp.json
• ~/.config/zed/settings.json
• ~/.continue/config.json

Zed servers are read from context_servers; Continue.dev from experimental.modelContextProtocolServers.

What It Reports

For each discovered MCP server:

• Server name - e.g., "filesystem", "postgres"
• Server type - e.g., "@modelcontextprotocol/server-filesystem"
• Command - Full command string
• Scope - Access scope (file paths, URLs)
• Environment variables - Names only, NOT values
• Status - Active or dormant

Configuration

Config is stored in:

• Windows: %LOCALAPPDATA%\MCPShield\config.json
• macOS: ~/Library/Application Support/MCPShield/config.json
• Linux: ~/.config/mcpshield/config.json

{
  "api_url": "https://api.mcpshield.app",
  "api_key": "mcp_sk_..."
}

Daemon Mode (Continuous Scanning)

Run the agent in daemon mode for automatic scheduled scanning:

# Default: scan every hour (3600 seconds)
mcpshield daemon

# Custom interval: scan every 5 minutes
mcpshield daemon --interval 300

The daemon will:

• Scan for MCP servers at the configured interval
• Report discovered servers to the backend
• Send heartbeat updates
• Log each scan cycle
• Shut down gracefully on Ctrl+C

Security

• Never sends credential values - Only environment variable names
• Local config is secure - API key stored locally
• HTTPS by default - All API communication encrypted

Development

# Install in development mode
pip install -e .

# Run tests
pytest

# Run locally against dev API
mcpshield configure --api-key YOUR_KEY --api-url http://localhost:8000

License

MIT License - see LICENSE file.