MCP Sheriff

Local-first security preflight for MCP client configs and AI agent tool setups.

MCP Sheriff scans Claude Desktop, Cursor, VS Code, Codex-style project configs, and custom MCP JSON files before an agent starts using them. It is built for the boring but dangerous layer where agent tools become real local commands: package runners, filesystem scopes, env vars, remote URLs, and tool descriptions.

npx mcp-sheriff scan

MCP Sheriff security preflight

Files scanned: 1
MCP servers:    3
Findings:       7 (2 critical, 4 high, 1 medium, 0 low, 0 info)

Why

AI agents are getting access to terminals, local files, browsers, SaaS APIs, and MCP servers. That power is useful, but it also means a small config mistake can expose tokens, run mutable packages, or grant a tool the whole home directory.

This project is shaped by the same risk area called out in the MCP security best practices, the OWASP Top 10 for LLM Applications, and agent frameworks that now treat guardrails as first-class workflow controls, such as the OpenAI Agents SDK guardrails.

MCP Sheriff is intentionally small:

• No runtime dependencies.
• No network calls.
• No LLM API required.
• Works in local development and CI.
• Produces text, JSON, or SARIF.

What It Finds

| Rule | Severity | Why it matters | | --- | --- | --- | | mcp.inline-secret | critical | Tokens or passwords are stored directly in MCP config. | | mcp.inline-auth-header | critical | Static authorization headers can leak through local tooling. | | mcp.remote-script-exec | critical | Launchers pipe downloaded code into an interpreter. | | mcp.latest-package | high | @latest is mutable and may run unreviewed code tomorrow. | | mcp.unpinned-package | medium | Package runners without exact versions drift over time. | | mcp.broad-filesystem-scope | high | MCP servers get root or home-directory access. | | mcp.container-breakout-risk | high | Docker socket/root mounts expose host-level power. | | mcp.prompt-injection-phrase | high | Config text contains instruction override or exfiltration phrases. | | mcp.hidden-unicode | medium | Invisible Unicode can hide or reorder instructions. | | mcp.insecure-http-url | high | Non-HTTPS remote URLs can be intercepted or modified. | | mcp.remote-url | low | Remote endpoints expand the trust boundary. |

Usage

Scan default locations:

npx mcp-sheriff scan

Scan a specific file or directory:

npx mcp-sheriff scan .cursor/mcp.json
npx mcp-sheriff scan .

Return JSON:

npx mcp-sheriff scan --json

Generate SARIF for code scanning:

npx mcp-sheriff scan . --sarif > mcp-sheriff.sarif

Fail CI on medium-or-worse findings:

npx mcp-sheriff scan . --fail-on medium

Default Config Locations

MCP Sheriff checks common local config paths when no path is provided:

• ./mcp.json
• ./.mcp.json
• ./.cursor/mcp.json
• ./.vscode/mcp.json
• ~/.cursor/mcp.json
• ~/Library/Application Support/Claude/claude_desktop_config.json
• ~/.config/Claude/claude_desktop_config.json
• %APPDATA%/Claude/claude_desktop_config.json
• %APPDATA%/Cursor/mcp.json

Example

Risky config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@latest", "/"],
      "env": {
        "GITHUB_TOKEN": "example-token-1234567890"
      }
    }
  }
}

MCP Sheriff reports:

• mutable @latest package usage
• broad / filesystem access
• inline token storage

CI

name: MCP Sheriff

on: [push, pull_request]

jobs:
  mcp-sheriff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx mcp-sheriff scan . --fail-on high

Project Status

MCP Sheriff is new and intentionally conservative. It is a static preflight scanner, not a sandbox, proxy, or vulnerability guarantee. The goal is to catch dangerous MCP setup patterns early enough that developers can fix them before giving agents real tools.

Roadmap

• Policy file support for allowed packages, paths, and hosts.
• Claude/Cursor config autofix suggestions.
• MCP server introspection for local stdio servers.
• GitHub Action wrapper.
• Baseline mode for gradually adopting the scanner in existing repos.

Development

npm install
npm test
npm run build
node dist/cli.js scan test/fixtures/risky-mcp.json --no-defaults

License

MIT