Back to Hub

opsecforge-mcp: keep secrets out of AI agent context

opsecforge-mcp is a local MCP server (stdio) for AI coding agents such as Claude Code, Codex and Cursor. The agent passes a file path or an environment variable name, the work happens on your machine, and only redacted or derived results come back. It makes no network requests, needs no account or API key, and has no telemetry. Redaction is heuristic, so read the limitations below before relying on it.

It is MIT-licensed, published on npm and listed in the official MCP Registry as io.github.cyberdroid2077/opsecforge. It reuses the code that powers the browser tools on this site. Requires Node.js 20 or newer.

Tools

Every tool is read-only and runs locally.

  • redact_file: Reads a local text file and returns it with secrets replaced by [REDACTED], plus a findings summary (type, count, line numbers). Original values are never returned.
  • scan_secrets: Pre-commit check of files, directories, or the staged git diff; lists file:line, secret type and a masked preview, never the original value.
  • redact_text: Redacts text the agent already has, to produce a safer copy to share outward. It cannot remove that text from the model context.
  • verify_webhook: Verifies a GitHub, Stripe or generic HMAC webhook signature offline; the secret is read only from a named environment variable, and a mismatch comes with diagnostics.
  • inspect_jwt: Decodes a JWT and returns header, claims, time-claim status and risk notes. Decoding is not verification; the signature is never checked.
  • file_checksum: SHA-256 or SHA-512 of a local file (up to 32 MiB), optionally compared with an expected value.

Install

Claude Code: plugin (MCP server + guard hook + skill)

/plugin marketplace add cyberdroid2077/opsecforge-tools
/plugin install opsecforge@opsecforge

The plugin adds the MCP server, a PreToolUse hook that blocks Read, Grep and Bash calls that would directly read .env, *.pem, *.key, id_rsa*, id_ed25519*, credentials, *.p12 and similar files (.env.example, .env.sample, .env.template and *.pub are allowed), and a skill that tells the agent which tool to use when. The hook's onFailure: "block" setting needs a recent Claude Code (v2.1.295 or later according to the hooks documentation); on older versions a hook that times out may be skipped instead of blocking.

Claude Code: MCP server only

claude mcp add opsecforge -- npx -y opsecforge-mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.opsecforge]
command = "npx"
args = ["-y", "opsecforge-mcp"]

Or: codex mcp add opsecforge -- npx -y opsecforge-mcp.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "opsecforge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "opsecforge-mcp"]
    }
  }
}

verify_webhook and inspect_jwt read secrets from environment variables by name; the variable must exist in the environment of the MCP server process. Do not paste the secret into chat. Optionally set OPSECFORGE_MCP_ROOTS to a path-delimiter-separated list of directories and the file tools refuse paths outside them.

Limitations

  • The hook is a best-effort guard, not a sandbox. It parses the text of tool calls and does not stop a script from reading a secret file indirectly (for example python app.py that opens .env, make, docker compose config), grep -r over a directory containing a .env, or commands that build file names from shell variables or command output.
  • For stronger protection, combine it with Claude Code's own controls: its sandbox and Read deny rules in settings.json, for example the following. Deny rules also have gaps and can produce prompts or false positives; test them.
    { "permissions": { "deny": ["Read(./.env)", "Read(./.env.local)", "Read(**/*.pem)", "Read(~/.ssh/**)"] } }
  • Redaction is heuristic and can miss secrets: custom token formats, secrets inside prose, base64-wrapped values, or values split across lines in unusual ways. It can also redact harmless values. Treat a clean result as “nothing matched”, not “nothing there”, and review output before sharing it.
  • Parameters and results of every MCP tool pass through the model. redact_text, and inspect_jwt with token, cannot keep what you hand them out of the context.
  • Codex and Cursor have no equivalent of the Claude Code PreToolUse hook, so there the tools are advisory: they only help if the agent chooses to call them instead of reading a file directly.
  • Redacted output still contains everything that was not matched (hostnames, usernames, internal URLs, personal data).
  • scan_secrets is not a replacement for a dedicated scanner with a maintained rule set in CI.
  • If a secret has already reached a model context, a log or a commit, rotate it.

Links

Related browser tools on this site