Metadata-Version: 2.4
Name: crowdstrike-aidr-mcpscanner
Version: 0.1.0
Summary: A command-line tool for analyzing MCP servers.
Author: CrowdStrike
Author-email: CrowdStrike <support@crowdstrike.com>
License-Expression: MIT
Requires-Dist: crowdstrike-aidr~=0.4.0
Requires-Dist: cyclopts~=4.3.0
Requires-Dist: fastembed~=0.7.4
Requires-Dist: fastmcp~=2.13.3
Requires-Dist: mcp~=1.22.0
Requires-Dist: pydantic~=2.12.5
Requires-Dist: pyjson5~=2.0.0
Requires-Dist: rich~=14.2.0
Requires-Dist: scipy~=1.16.3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# MCPScanner

MCPScanner is a command-line tool for analyzing MCP servers. It does the
following:

1. **Discovers MCP Servers**: It automatically searches for MCP server
   configuration files in well-known locations on the host system.
2. **Analyzes Tools and Resources**: It connects to each discovered server to
   fetch the list of available tools and resources.
3. **Security Scanning with CrowdStrike AIDR**: It uses the CrowdStrike AIDR
   service to scan the tools for malicious entities and prompts.
4. **Generates Reports**: It creates a JSON report (default `mcpscanner.json`)
   containing the analysis results.
5. **Detects Changes**: It can compare the current state of a server's tools
   with a previous report and display a diff if any changes are detected.
6. **Finds Similar Tools**: It can identify tools with similar functionality.

![Sample output](./.github/assets/sample.png)

## Installation

```bash
pip install -U crowdstrike-aidr-mcpscanner
```

## Configuration

Before using MCPScanner, you need to set the `CS_AIDR_TOKEN` environment
variable to a CrowdStrike AIDR API token and the `CS_AIDR_BASE_URL_TEMPLATE`
environment variable to the base URL of the CrowdStrike AIDR API.

```bash
export CS_AIDR_TOKEN="your_token_here"
export CS_AIDR_BASE_URL_TEMPLATE="https://api.crowdstrike.com/aidr/{SERVICE_NAME}"
```

## Usage

The primary command is `scan`, which runs the analysis.

```bash
mcpscanner scan
```

### Options

| Parameter                        | Description                                                                      | Default                                                     |
| -------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `--input <PATH>`                 | The input file containing a previous report to compare against.                  | `mcpscanner.json`                                           |
| `--output <PATH>`                | The file where the new report will be saved.                                     | `mcpscanner.json`                                           |
| `--list-tools`                   | If set, the names of all tools for each MCP server will be listed in the output. | `False`                                                     |
| `--mcp-config-files <FILES>`     | A list of files to discover MCP servers from.                                    | A list of well-known paths for different operating systems. |
| `--similarity-threshold <FLOAT>` | The threshold (between 0.0 and 1.0) for two tools to be considered similar.      | `0.96`                                                      |
| `--syntax-theme <THEME>`         | The syntax theme to use for displaying JSON diffs.                               | `github-dark`                                               |
| `--poll-result-timeout`          | Timeout (seconds) for polling AIDR results.                                      | `30`                                                        |
