About MCP Customs
MCP Customs is a local CLI for checking MCP servers for common security risks before installation. Its auditable heuristic scans run offline without uploading data; results may include false positives and miss issues that deeper analysis could find.
Key features
- 01Scan MCP servers offline
- 02Check shell execution and dynamic code
- 03Flag file access and credential risks
- 04Detect hidden instructions in tool descriptions
- 05Generate SARIF reports and badges
Use cases
- 01Review MCP server code before installing
- 02Scan in CI and fail on selected severity
- 03Create a security badge for a project README
MCP support
It is not an MCP server; it is a CLI that inspects MCP server code and does not connect to MCP servers or clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEmcp-customs
Inspect an MCP server for common security risks before you install it. Runs fully offline. No telemetry, no cloud upload, no account.
npx mcp-customs scan ./some-mcp-server
──────────────────────────────────────────────────────
MCP-CUSTOMS INSPECTION REPORT
──────────────────────────────────────────────────────
target ./some-mcp-server
files scanned 14
score 62 / 100
stamp [ REVIEW ]
──────────────────────────────────────────────────────
[HIGH] MCP002 — Unsanitized file path (possible path traversal)
server.js:41 return fs.readFileSync(userPath, 'utf8');
fix: Resolve the path against an allowed base directory ...
Why
Developers install MCP servers the way they used to install npm packages — quickly, trusting the name, and moving on. An MCP server can read your files, call your APIs, and execute commands on your behalf. Almost nobody checks what it can actually do before connecting it to their agent.
mcp-customs is the "audit before install" step, run locally, in seconds.
What it checks (v0.1)
| Rule | Severity | What it looks for |
|---|---|---|
| MCP001 | critical | Shell command execution with unsanitized interpolation |
| MCP002 | high | File reads/writes without a path-traversal guard |
| MCP003 | critical | eval() / dynamic code execution |
| MCP004 | high | Hardcoded API keys / credentials |
| MCP005 | critical | Tool descriptions containing hidden-instruction language (prompt injection via the tool's own metadata) |
| MCP006 | medium | Outbound network calls combined with environment-variable reads (possible exfiltration) |
| MCP007 | low | No permissions/scopes declared in the manifest |
These are heuristic, regex-based checks — fast and fully auditable in one sitting, not a dataflow analysis. They will produce false positives and will miss things a deeper analysis would catch. Treat a CLEARED stamp as "nothing obvious," not "verified safe."
CI usage
# .github/workflows/mcp-customs.yml
- run: npx mcp-customs scan . --sarif results.sarif --fail-on high
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
Get a badge for your README
npx mcp-customs scan . --badge --name your-server-name
Roadmap
- Publish scan results to a public registry (mcp-customs.dev) with searchable trust scores
- Dynamic/sandboxed analysis (catch what static checks miss)
- Python-specific AST checks (current Python rules are regex-only)
- Community flagging / verification on registry entries
License
Apache-2.0. No open-core trap — this CLI stays free either way. If a hosted registry/dashboard ships later, that's a separate paid product; this tool's local scanning will never require it.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.