Metadata-Version: 2.4
Name: mcpshield-agent
Version: 0.6.0
Summary: MCPShield Agent - AI Agent Security Scanner for MCP servers
Author-email: David Cooper <hello@mcpshield.app>
License-Expression: MIT
Project-URL: Homepage, https://mcpshield.app
Project-URL: Repository, https://github.com/RunTimeAdmin/MCPShield
Project-URL: Issues, https://github.com/RunTimeAdmin/MCPShield/issues
Project-URL: Documentation, https://mcpshield.app/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"

# MCPShield Agent

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

## Installation

```bash
# Install from PyPI
pip install mcpshield-agent

# Or install from source
pip install -e .
```

## Quick Start

```bash
# 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:

```bash
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:

```python
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:

```bash
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:

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

Tools it exposes:

| Tool | Purpose |
|------|---------|
| `score_mcp_server` | Score one server from its launch spec (`command`, `args`, `env`) — the risk-authority call |
| `scan_mcp_config` | Score every server in a config file's contents (standard / Zed / Continue.dev shapes) |
| `scan_local_machine` | Discover and score every MCP server configured on this host |

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

| Command | Description |
|---------|-------------|
| `mcpshield configure --api-key KEY` | Configure agent with API key |
| `mcpshield scan` | Scan and score locally; also report if configured |
| `mcpshield scan --deep` | Also connect to active servers and scan tool descriptions |
| `mcpshield scan --dry-run` | Scan and score locally, never report |
| `mcpshield daemon` | Run continuous scheduled scanning |
| `mcpshield status` | Show agent status |
| `mcpshield list` | List found servers (no report) |
| `mcpshield --version` | Show version |

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

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

```bash
# 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

```bash
# 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.
