Unified security scanner for MCP servers with config, pentest, and repo-scan modes. Generates SARIF reports for CI/CD integration, detects secrets, vulnerabilities, and misconfigurations via token and LLM analyzers.
MCP X-Ray is a unified open-source security scanning and penetration testing solution for Model Context Protocol (MCP) servers. It generates production-ready SARIF reports for seamless integration with security tooling and CI/CD pipelines. Scan results can be optionally uploaded to Traceforce Atlas for centralized security management and tracking. Atlas has over 600 MCPs in its registry, providing a comprehensive security assessment database for the MCP ecosystem.
# Clone the repository
git clone https://github.com/traceforce/mcp-xray
cd mcp-xray
# Install required dependencies (buf, etc.)
make install-dependencies
# Build everything (generates protobuf code and builds the binary)
# The binary will be created as `mcpxray` in the current directory
make all
Scan MCP configs for security issues; run before pentest to baseline your setup.
# Scan a specific MCP config file (uses token analyzer by default)
./mcpxray config-scan /path/to/mcp/config.json
# Scan all known MCP config paths automatically for Cursor, Claude and Windsurf.
# Known config locations (relative to home directory):
# ~/.cursor/mcp.json (Cursor)
# ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
# ~/.codeium/windsurf/mcp_config.json (Windsurf)
./mcpxray config-scan --scan-known-configs
# Use LLM analyzer for more extensive and deepr analysis
./mcpxray config-scan /path/to/mcp/config.json --analyzer-type llm --llm-model claude-3-5-sonnet-20241022
# Specify custom output file
./mcpxray config-scan /path/to/mcp/config.json --output custom-report.sarif.json
Detection Capabilities:
Execute security test plans by making actual tool calls against MCP servers. LLMs are required to run the pentest. Run this before actual deployment in production.
# Run pentest with auto-generated test plan (requires LLM model)
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
# Use a custom test plan YAML file
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
Detection Capabilities: Code execution, SSRF, path traversal, authorization bypass, input injection, information disclosure, and DoS vulnerabilities
Scan the codebase for vulnerabilities; use when you own or can change the code.
# Scan current directory
./mcpxray repo-scan
# Scan a specific repository
./mcpxray repo-scan /path/to/repository
# Specify custom output file
./mcpxray repo-scan --output custom-report.sarif.json
Detection Capabilities:
MCP X-Ray generates reports in SARIF (Static Analysis Results Interchange Format) format, which is widely supported by security tools and CI/CD platforms.
Upload scan results to Traceforce Atlas for centralized security management, reporting, and tracking over time. Add the --upload flag to any scan command. Use --clean-up to remove generated files after successful upload.
Environment variables required:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRETThese credentials can be downloaded from the settings page on the Atlas UI.
# Upload config scan results
./mcpxray config-scan /path/to/mcp/config.json --upload
# Upload with cleanup
./mcpxray config-scan /path/xia-add-registry-imageto/mcp/config.json --upload --clean-up
# Upload pentest results
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5 --upload
Example scan outputs are available in examples/findings/.
Example MCP configuration files are available in the examples/mcp_configs/ directory.
An example MCP Server is available in the examples/mcp_server/ directory:
mcp_server.py: FastMCP server using streamable-http transportmcp.json: Configuration file for connecting to the serverREADME.md: Instructions for setting up and scanning the serverMCP X-Ray provides two methods for analyzing tool security:
The token analyzer uses rule-based pattern matching to quickly detect security issues in tool descriptions. It's fast, doesn't require API keys, and works offline. Token analyzer uses two types of rules:
internal/configscan/tokenanalyzer/token_rules.yaml. Each rule specifies:
internal/yararules/unsafe_patterns.yar. These rules detect unsafe system command patterns.Usage:
mcpxray config-scan --analyzer-type token
The LLM analyzer uses large language models for deep semantic analysis of tool descriptions, providing more comprehensive security insights.
Usage:
mcpxray config-scan --analyzer-type llm --llm-model <model-name>
By default, the pentest tool uses an LLM to automatically generate test plans based on the available tools from MCP servers. Test plans can also be customized and provided as YAML files. Test plans are YAML files containing test cases with input arguments and expected outputs.
Default behavior (LLM-generated test plan):
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
Custom test plan:
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
MCP X-Ray supports the following LLM providers for tool analysis:
claude-sonnet-4-5ANTHROPIC_API_KEY environment variablegpt-5OPENAI_API_KEY environment variablearn:aws:bedrock: and containing llamaarn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0For LLM-based tool analysis, configure your LLM API credentials:
export ANTHROPIC_API_KEY=your-api-key
export OPENAI_API_KEY=your-api-key
Each provider requires its own specific environment variable. The tool automatically detects which provider to use based on the model name.
For AWS Bedrock models, configure AWS credentials using one of the standard AWS SDK methods:
# Option 1: Environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1
# Option 2: AWS credentials file (~/.aws/credentials)
# Option 3: IAM role (when running on EC2/ECS/Lambda)
MCP X-Ray uses AWS SDK that will automatically load credentials from the environment, credentials file, or IAM role.
Contributions are welcome! Please ensure that: