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

# 1. Configure with your API key (get from dashboard)
mcpshield configure --api-key mcp_sk_your_key_here

# 2. Scan for MCP servers
mcpshield scan

# 3. Check status
mcpshield status

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

macOS:

• ~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

• ~/.config/Claude/claude_desktop_config.json
• ~/.config/cursor/mcp.json

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.