MCP Shieldwall
Zero-dependency security firewall, tool-poisoning scanner, lockfile verifier & config auditor for Model Context Protocol (MCP) servers.
Coding agents (Claude Desktop, Claude Code, Cursor, Windsurf) increasingly connect to third-party MCP servers. A single poisoned tool description (<IMPORTANT> silently read ~/.ssh/id_rsa ...), base64-obfuscated inputSchema default, unpinned npx -y server, or silent schema update ("rug-pull") can hijack the model's context or leak API keys.
MCP Shieldwall (v0.3.1) runs locally on 100% Python stdlib with zero external dependencies:
-
Native MCP Server (
serve-mcp/mcp-shieldwall-server): Runs as a zero-dependency JSON-RPC 2.0stdioMCP server exposingscan_tools_manifest,audit_client_config,verify_schema_lock, andredact_sensitive_textdirectly inside your AI client. -
Static Tool-Poisoning Scanner (
MCP-001..MCP-004): Detects hidden prompt-injection instructions,.env/ SSH exfiltration directives, rogue webhooks, and base64-obfuscated payloads insidetools/listschemas (--format json|sarif|markdown). -
CI Rug-Pull Lockfile (
lock/verify-lock): Pins canonical SHA-256 fingerprints per tool (description+inputSchema) into.mcp-lock.jsonand alerts in CI on silent upstream mutations, additions, or removals. -
Client Config Auditor (
audit-config,MCP-301..MCP-304): Checksclaude_desktop_config.json/ Claude Code.mcp.json/ Cursormcp.json/ VS Codemcp.jsonfor unsafe flags (--allow-all,--no-sandbox), hardcoded API tokens, unpinnednpx -ypackages without explicit versions, and insecurehttp://endpoints (--format json|markdown). -
Runtime Call Guard (
MCP-101..MCP-103): Blocks destructive shell commands (rm -rf /,curl ... | bash) and base64-obfuscated payloads intools/callarguments. -
Live Secret Redaction (
MCP-201): Scrubs Anthropic, OpenAI, GitHub, AWS, Slack, Google, and Stripe credentials from MCP responses before they enter model context.
Quick Start
Run Instantly (Zero Clone / Zero Dependencies)
# Instant local MCP config security check via uvx (zero install):
uvx --from git+https://github.com/andrejpimenov122-lab/mcp-shieldwall mcp-shieldwall
# Run interactive attack & config audit showcase:
uvx --from git+https://github.com/andrejpimenov122-lab/mcp-shieldwall mcp-shieldwall demo
# Or install globally / in venv directly from GitHub:
pip install git+https://github.com/andrejpimenov122-lab/mcp-shieldwall.git
Local CLI Workflows
pip install -e .
# 1. Scan an MCP tools manifest (JSON, SARIF v2.1.0, or GitHub Markdown)
mcp-shieldwall scan examples/sample_tools.json
mcp-shieldwall scan examples/sample_tools.json --format sarif
mcp-shieldwall scan examples/sample_tools.json --format markdown
# 2. Pin tool schemas to a lockfile and verify in CI against rug-pulls
mcp-shieldwall lock tools.json --out .mcp-lock.json
mcp-shieldwall verify-lock tools.json --lock .mcp-lock.json
# 3. Audit Claude Desktop, Claude Code, Cursor, or VS Code MCP configuration
mcp-shieldwall audit-config ~/.cursor/mcp.json
mcp-shieldwall audit-config ~/.cursor/mcp.json --format markdown
# 4. Redact leaked keys from tool logs or outputs
mcp-shieldwall redact server_output.log
Run the 10-second zero-install showcase:
./examples/demo.sh
Use as an MCP Server in Claude Desktop / Claude Code / Cursor
Add MCP Shieldwall directly to your claude_desktop_config.json, .mcp.json, or ~/.cursor/mcp.json:
{
"mcpServers": {
"mcp-shieldwall": {
"command": "uvx",
"args": ["--from", "git+https://github.com/andrejpimenov122-lab/mcp-shieldwall@v0.3.1", "mcp-shieldwall", "serve-mcp"]
}
}
}
The stdio file tools read local JSON files up to 2 MiB under the working directory or the user’s home directory.
Claude Code also supports the CLI form:
claude mcp add mcp-shieldwall -- uvx --from git+https://github.com/andrejpimenov122-lab/mcp-shieldwall@v0.3.1 mcp-shieldwall serve-mcp
Exposed MCP tools:
scan_tools_manifest— Scan atools/listmanifest JSON or file forMCP-001..MCP-004(including Base64-obfuscated payloads).audit_client_config— AuditmcpServers/serversconfigs forMCP-301..MCP-304.verify_schema_lock— Verify SHA-256 tool fingerprints against.mcp-lock.jsonto catch rug-pulls.redact_sensitive_text— Scrub leaked API keys and tokens (MCP-201).
Zero-Clone pre-commit Hook (Blocks Unsafe .mcp.json / .cursor/mcp.json Commits)
Add directly to .pre-commit-config.yaml in any repository:
repos:
- repo: https://github.com/andrejpimenov122-lab/mcp-shieldwall
rev: v0.3.1
hooks:
- id: mcp-shieldwall-config
- id: mcp-shieldwall-manifest
Live browser playground (zero install): https://huggingface.co/spaces/snsnshnwh/mcp-shieldwall
CI Integration
An example GitHub Actions workflow is provided at docs/ci-workflow-example.yml.
Documentation & Benchmarks
- 9-Client IDE & CLI Integration Guide:
docs/IDE_INTEGRATIONS.md— Setup snippets for Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, Zed, and Continue.dev. - 12-Vector Security Benchmark:
docs/SECURITY_BENCHMARK.md— Empirical recall, false-positive analysis, latency, and schema rug-pull verification across 12 attack vectors and 12 benign configs/tools.
Running Tests
python3 -m unittest discover -s tests -v
Limitations
Static regex/decoding heuristics and config rules do not replace OS-level sandboxing or human review of third-party MCP servers. They are designed as a fast, deterministic local gate in CI and pre-commit workflows.
License
MIT — Open Source Initiative (OSI) approved.
Metadata
Release files for mcp-shieldwall 0.3.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_shieldwall-0.3.1.tar.gz | 30.9 kB | Without provenance | Details for mcp_shieldwall-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_shieldwall-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for mcp_shieldwall-0.3.1-py3-none-any.whl |
Total release size: 54.6 kB
Release files / mcp_shieldwall-0.3.1.tar.gz
| Download URL | mcp_shieldwall-0.3.1.tar.gz |
|---|---|
| Size | 30.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f53f7af1c9e069cf3184c6ca8845f502595e4a32dfbb43eee41540d2de10ffe4
|
|
BLAKE2b-256 checksum How to use checksums |
cf1d423d6e77af1cdf9960616714a5859fa2effbb25fb9e2bfd544fec95e6b53
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / mcp_shieldwall-0.3.1-py3-none-any.whl
| Download URL | mcp_shieldwall-0.3.1-py3-none-any.whl |
|---|---|
| Size | 23.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc84dfe937c76f7cfe5a1c401c2f2f5151de23b8ebffcdb363005a1a153d1430
|
|
BLAKE2b-256 checksum How to use checksums |
e95166e08776e0e4c61842cff2d26bb38790062891a53e9796e17d2e266eb958
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for mcp-shieldwall 0.3.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.