mcp-riskmap
mcp-riskmap is a local-first static auditor for MCP and agent-tool repositories. It looks for risky MCP configuration, shell-enabled tool handlers, prompt-injection-like tool descriptions, and missing maintainer guidance without starting untrusted MCP servers.
This project is intentionally small and conservative. It is designed for maintainers who want a quick review signal in local development, pull requests, and GitHub Code Scanning.
Why this exists
MCP servers often expose tools that can touch files, shells, networks, credentials, or local developer state. Reference servers and community examples are useful, but each maintainer still needs a threat model and basic safeguards before sharing configs or accepting tool changes.
mcp-riskmap focuses on static signals that are cheap to review:
- MCP config that starts through
cmd,powershell,bash, orsh - Remote install pipelines such as
curl ... | shorcurl ... | iex - Secret-like environment variables passed into MCP servers
- Full process environment passthrough into Python or JavaScript child processes
- Python
subprocess(..., shell=True),os.system,eval, andexec - JavaScript
child_process.execandspawn(..., { shell: true }) - Python and JavaScript filesystem access that appears to use user-controlled path input
- Tool text that looks like model-control prompt injection
- JSON tool metadata that looks like prompt-injection or tool-poisoning text
- Missing
AGENTS.md,SECURITY.md, orLICENSE
Install
From PyPI:
python -m pip install --upgrade mcp-riskmap
From a checkout:
python -m pip install -e .
From GitHub:
python -m pip install "git+https://github.com/vawkdh-job/mcp-riskmap.git@v0.2.1"
For development without installing:
$env:PYTHONPATH = "src"
python -m mcp_riskmap.cli scan examples/unsafe-mcp-server
python -m mcp_riskmap.cli --version
Usage
mcp-riskmap scan .
mcp-riskmap scan . --format json
mcp-riskmap scan . --format markdown --output report.md
mcp-riskmap scan . --format sarif --output results.sarif --profile ci
mcp-riskmap scan . --exclude "examples/**" --exclude "tests/**"
mcp-riskmap scan . --profile ci
mcp-riskmap baseline . --output mcp-riskmap-baseline.json
mcp-riskmap baseline-check . --baseline mcp-riskmap-baseline.json
mcp-riskmap scan . --baseline mcp-riskmap-baseline.json --profile ci
--profile ci returns exit code 1 when at least one finding is high or critical.
Use --exclude for reviewed fixture directories, generated output, or intentionally unsafe examples that should not block CI.
Use --profile for common fail policies:
local: report findings without failing.audit: report findings without failing, intended for review artifacts.ci: fail on high or critical findings.release: fail on medium, high, or critical findings.
--fail-on overrides the selected profile.
Use baseline when adopting mcp-riskmap in a repository that already has reviewed findings. The baseline records current findings, and scan --baseline reports only findings that are not already in the baseline.
Use baseline-check to audit baseline drift. It reports baseline entries that are still active, entries that are now stale because the finding disappeared, and current findings that are not in the baseline. It returns exit code 1 when new findings are present.
See docs/baseline-ratchet.md for the recommended baseline workflow.
Examples
examples/unsafe-mcp-server/contains intentionally risky MCP config and tool-handler patterns for scanner demonstrations.examples/safe-mcp-server/contains a safer file-read pattern using a resolved base directory boundary check.docs/rules.mdcontains unsafe examples, safer patterns, and review notes for each rule.
Example output
SEVERITY RULE LOCATION MESSAGE
-------- ------------------------- ------------ ------------------------------------------------
CRITICAL MCP-CONFIG-REMOTE-INSTALL mcp.json:5 MCP server 'unsafe-demo' downloads and executes...
HIGH PY-SHELL-TRUE server.py:6 A Python tool handler can pass input through a shell.
HIGH JS-CHILD-PROCESS-EXEC server.js:4 A JavaScript tool handler can pass input through a shell.
Output formats
table: compact terminal outputjson: automation-friendly structured outputmarkdown: issue and release-note friendly reportsarif: GitHub Code Scanning compatible output
Structured outputs redact secret-like evidence values before writing JSON or SARIF.
Reviewed suppressions
If a maintainer reviews a finding and accepts the risk, add a narrow suppression on the same line or the previous line:
# mcp-riskmap: ignore PY-SHELL-TRUE
subprocess.run(command, shell=True)
Use rule-specific suppressions where possible. mcp-riskmap: ignore suppresses all rules on the next line and should be reserved for generated or documented fixture code.
GitHub Action
This repository includes a composite GitHub Action:
name: mcp-riskmap
on:
pull_request:
push:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v6
- uses: vawkdh-job/mcp-riskmap@v0.2.1
with:
path: .
format: sarif
output: mcp-riskmap.sarif
profile: ci
exclude: |
examples/**
tests/**
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: mcp-riskmap.sarif
Additional copy-paste workflows are available in docs/ci-examples.
Safety stance
mcp-riskmap does not execute MCP servers. It reads files and reports static findings. That means it will miss runtime-only behavior, but it is safer for quick review of unknown configs and pull requests.
Why static only?
Some MCP scanners inspect live tool descriptions by starting configured servers. That can be useful, but it is risky when a reviewer is looking at an unknown repository or pull request. mcp-riskmap is meant to run earlier in the review flow: it reads files, flags obvious risk, and produces review artifacts without executing commands from the target project.
Compared with dynamic scanners
mcp-riskmap is not a replacement for dynamic MCP inspection. It is a first-pass guardrail for maintainers who need quick review signals in CI and code review.
| Area | mcp-riskmap | Dynamic scanners |
|---|---|---|
| Starts scanned MCP servers | No | Often yes |
| Safe for unknown PRs | Designed for this | Depends on sandboxing |
| CI/SARIF friendly | Yes | Depends on tool |
| Runtime behavior coverage | Limited | Better |
| Static source/config review | Primary focus | Varies |
Current limitations
- Rules are conservative regex/static checks, not full taint analysis.
- The scanner does not inspect live MCP tool responses.
- Secret detection is key-name based and does not do high-entropy scanning.
- JavaScript and Python analyzers focus on common high-risk patterns first.
Roadmap
- Improve tool metadata checks for MCP prompt-injection and tool-poisoning patterns.
- Add Semgrep-compatible pattern export.
See ROADMAP.md for issue-sized milestones.
OpenAI Codex for OSS fit
This project is intended to be maintained as an open-source security and maintainer automation tool. It includes tests, CI, SARIF output, GitHub Code Scanning support, a published PyPI package, examples, security docs, contribution guidance, AGENTS.md, protected-main workflow notes, and tagged releases.
Codex/API credits would be useful for reviewing rule changes, generating regression tests, triaging issues, improving documentation, and producing release notes. AI output should be reviewed by maintainers before merge.
See docs/codex-for-oss.md for application-specific maintainer workflow notes.
Metadata
Release files for mcp-riskmap 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_riskmap-0.2.1.tar.gz | 25.6 kB | With provenance | Details for mcp_riskmap-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_riskmap-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for mcp_riskmap-0.2.1-py3-none-any.whl |
Total release size: 50.3 kB
Release files / mcp_riskmap-0.2.1.tar.gz
| Download URL | mcp_riskmap-0.2.1.tar.gz |
|---|---|
| Size | 25.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08b40260804cf9bc914f6f97845d9cca3cc2fbc5aa7d29bb3fe45a1d431689a9
|
|
BLAKE2b-256 checksum How to use checksums |
56f17b97d6732ae395c1f3ca12910af8597543fde905f27780d04e467b3fae45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / mcp_riskmap-0.2.1-py3-none-any.whl
| Download URL | mcp_riskmap-0.2.1-py3-none-any.whl |
|---|---|
| Size | 24.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5023fddcaba03a5bfb8b6c2f378c7e8c30b81cf4f08496b472d51e4422b455aa
|
|
BLAKE2b-256 checksum How to use checksums |
91c1ce5d4fa3a5c9096c5a86e0a8c786e139ad7ba91ab5fc48e83032dddf6ff4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logSecurity for mcp-riskmap 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_riskmap-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.