mcp-scanner

A security scanner for Model Context Protocol servers. It scans live servers,
source trees, and packages, and reports both findings and coverage gaps.
SAFE requires every required analyzer to finish without a reported coverage
gap:

COMPLETED + SAFE      required analysis ran, nothing blocking
COMPLETED + UNSAFE    required analysis ran, something blocking
PARTIAL   + UNKNOWN   an analyzer could not finish
ERROR     + UNKNOWN   an analyzer failed
SKIPPED   + UNKNOWN   no analyzer produced usable analysis

Timeouts, crashes, unexplained files, and missing statuses downgrade the scan.
An analyzer error is never self-excusing; only an explicit best-effort policy
can exempt it. A known limitation is that any recorded file-skip reason accounts
for all skipped files, so some incomplete file scans can still be SAFE.

Install

go install github.com/devlab-group/mcp-scanner/cmd/mcp-scanner@latest

Signature matching requires libyara and a tagged build:

# Debian, Ubuntu
sudo apt install libyara-dev pkg-config

# Fedora, RHEL
sudo dnf install yara-devel pkgconf-pkg-config

# macOS
brew install yara pkg-config

make build-yara

See the YARA installation guide
for source builds. If /usr/local/lib is outside the linker path, run
sudo ldconfig or set LD_LIBRARY_PATH=/usr/local/lib. Builds without the
tag report YARA as unavailable.

Use

Scan a remote server:

mcp-scanner remote https://mcp.example.com/mcp

Scan a trusted stdio server as a child process:

mcp-scanner stdio -- npx -y @example/mcp-server

This runs the target on your machine with your privileges. For untrusted code,
use source or package, which do not execute it. runtime stdio runs only an
absolute, statically linked ELF executable in a container and needs a trusted
snapshot.

Scan the servers declared in your MCP client configuration:

mcp-scanner known-configs --run

--run scans remote entries. Stdio entries are skipped unless you also pass
--include-stdio, and any skipped stdio entry makes the command exit 3.

Scan a source tree, or a published package:

mcp-scanner source ./my-mcp-server
mcp-scanner package npm:@example/[email protected]

Gate a pipeline:

mcp-scanner remote https://mcp.example.com/mcp --format sarif --output results.sarif --fail-on high

Exit codes:

Code	Meaning
0	scan completed, policy passed
1	bad flags or configuration
2	scan completed, policy failed
3	scan could not determine an answer
4	the scanner itself broke

--fail-on defaults to high, so a pipeline that never sets it still stops
on a high or critical finding. Pass --fail-on none to report without
gating.

Treat exit code 3 as a pipeline failure. It means the scan did not finish.

What it checks

MCP protocol conformance, capability declarations against actual behaviour,
and how the server handles malformed input
Authentication, token validation and session binding
Prompt injection, tool poisoning, hidden Unicode and credential harvesting
in the text a server hands a model
Source-to-sink dataflow across files, in Go, Python, JavaScript, TypeScript,
Java and Rust
Mismatch between what a tool says it does and what its handler reaches
Dependency vulnerabilities and package contents, without running install
scripts
Optional sandboxed confirmation of static findings
Optional model-assisted review that supplements deterministic evidence

Scanning safely

By default, the scanner discovers capabilities without invoking real tools.

--active-probes none        connect and read declarations
--active-probes safe        also send malformed protocol messages a correct server must reject
--active-probes tool-calls  permit tools named with --allow-tool-call

safe is the default. Its tools/call probes use an invalid name or a name
that does not exist, which a conforming server rejects before dispatch.
A loose server may dispatch such a request before validating the name. No
setting invokes arbitrary declared tools on a live server or sends intentionally
destructive requests. The runtime analyzer can invoke declared tools only inside
its sandbox.

Documentation

Development

make check      # gofmt, vet, test, race, vulnerability scan, version check
make build

Three rules hold the design together: SAFE must mean the analysis ran,
every finding carries evidence, and every analyzer reports what it did not
look at.

Security

Report vulnerabilities privately. See SECURITY.md.

License

Apache License 2.0. See LICENSE. Binaries also include the third-party
components listed in THIRD_PARTY_NOTICES.