NuGuard Plugin and MCP Guide

The plugin wires up slash commands, agents, and skills in one step — no manual config editing required.

From the Claude Code UI: open the plugin marketplace, search for NuGuard, and click Install.

From the terminal:

claude plugin marketplace add NuGuardAI/nuguard
claude plugin install nuguard

From inside a Claude Code chat:

/plugin marketplace add NuGuardAI/nuguard
/plugin install nuguard

After installation, run the configuration wizard once per project:

/nuguard-config

The wizard collects your LLM API key, model, target URL, and auth details, then writes them to .claude/nuguard.local.md (project-local, gitignored). Every NuGuard command and the AI security-review skill read this file automatically — you never need to repeat credentials.

What's included:

• /nuguard-scan, /nuguard-redteam, /nuguard-config, /nuguard-init slash commands
• ai-security-review and sbom-analysis skills that Claude invokes automatically
• security-auditor agent for autonomous end-to-end audits
• Credentials stored per-project in .claude/nuguard.local.md, never globally

Tip: If you have multiple projects, run /nuguard-config in each one to set project-specific targets and credentials. The slash commands will always use the config from the current project context.

Try it:

use nuguard to generate an SBOM for this project and analyze it for security risks

⬆ Back to agent picker

Claude Desktop doesn't support the plugin marketplace, so it connects to NuGuard as an MCP server instead. Pick whichever option matches what's already on your machine — you only need one.

Option A — you have Python installed (recommended):

Install the package once with uv (fast, recommended) or plain pip:

uv pip install "nuguard[mcp]"

pip install "nuguard[mcp]"

Option B — you don't have Python, but you do have Node.js:

npx (bundled with Node.js) downloads and runs NuGuard automatically the first time it's needed — nothing to install ahead of time.

Either way, add this to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If you installed via Option A (uv/pip):

{
  "mcpServers": {
    "nuguard": {
      "command": "nuguard-mcp",
      "env": {
        "LITELLM_API_KEY": "your-api-key-here",
        "NUGUARD_DEFAULT_CONFIG": "/absolute/path/to/nuguard.yaml"
      }
    }
  }
}

If you're using Option B (npx):

{
  "mcpServers": {
    "nuguard": {
      "command": "npx",
      "args": ["-y", "@nuguardai/nuguard"],
      "env": {
        "LITELLM_API_KEY": "your-api-key-here",
        "NUGUARD_DEFAULT_CONFIG": "/absolute/path/to/nuguard.yaml"
      }
    }
  }
}

Restart Claude Desktop after saving. The NuGuard tools appear in the tools panel (hammer icon).

[!TIP] Using a virtual environment? Activate it first, or point directly to the venv's binary:

{ "command": "/path/to/.venv/bin/nuguard-mcp" }

[!TIP] Have uv and want to skip a permanent install entirely? Use uvx instead, which runs NuGuard on demand:

{
  "mcpServers": {
    "nuguard": {
      "command": "uvx",
      "args": ["--from", "nuguard[mcp]", "nuguard-mcp"],
      "env": { "LITELLM_API_KEY": "your-api-key-here" }
    }
  }
}

⬆ Back to agent picker

NuGuard runs as a standard MCP server, so any editor or agent that supports MCP — Cursor, Windsurf, Cline, and others — can connect to it using the same server definition, even though each editor stores that config in a different place. Check your editor's MCP / tool settings for the exact file location, then add:

{
  "mcpServers": {
    "nuguard": {
      "command": "npx",
      "args": ["-y", "@nuguardai/nuguard"],
      "env": {
        "LITELLM_API_KEY": "your-api-key-here",
        "NUGUARD_DEFAULT_CONFIG": "/absolute/path/to/nuguard.yaml"
      }
    }
  }
}

npx (bundled with Node.js) is the lowest-friction option since it needs nothing pre-installed. If you have Python and uv installed instead, swap the command and args for:

"command": "nuguard-mcp"

(after running uv pip install "nuguard[mcp]" — see Claude Desktop above for the full install step) or:

"command": "uvx",
"args": ["--from", "nuguard[mcp]", "nuguard-mcp"]

Reload your editor's window after saving the config. The NuGuard tools should appear wherever your editor lists connected MCP tools.

⬆ Back to agent picker

Smithery is a registry that many coding agents (Cursor, Windsurf, Claude Desktop, Claude Code, and others) can install MCP servers from directly, without you hand-writing any JSON config.

smithery mcp add NuGuardAI/nuguard

Or open smithery.ai/servers/NuGuardAI/nuguard and click Connect.

During install, Smithery prompts for three optional settings:

Secrets are passed as environment variables to the nuguard-mcp process and never travel through the agent's context.

[!NOTE] Smithery provisions only the seven NuGuard tools. Slash commands, skills, and the security-auditor agent require the Claude Code plugin.

⬆ Back to agent picker

No chat interface involved — you're calling NuGuard from a pipeline or script. Install the package directly and use the nuguard CLI (see the Quick Start guide) instead of the MCP server:

uv pip install nuguard   # recommended if you have uv
pip install nuguard      # otherwise

⬆ Back to agent picker

Initialize a nuguard.yaml config file in a project directory. Also creates canary.example.json and cognitive-policy.md.

Generate an AI Bill of Materials from source code or a git repository. Either source or from_repo must be provided.

Run static risk analysis on an AI-SBOM.

Runs the unified security scan pipeline. Defaults to SBOM generation plus static analysis; include policy,redteam in steps for policy and red-team validation. Returns artifact paths (sbom.json, findings.json, findings.sarif, report.md) and a severity summary.

Run intent-aware behavioral testing against a live AI application. Static mode checks SBOM–policy alignment without hitting the live app. Dynamic mode sends probe conversations and judges each turn for intent drift, policy violations, and data leakage.

Run adversarial red-team testing against a live AI application. Requires a running target app and an LLM configured for attack payload generation (NUGUARD_REDTEAM_LLM_MODEL).

Cross-check a Cognitive Policy against an AI-SBOM and run compliance assessments (OWASP LLM Top 10, NIST AI RMF, EU AI Act).

This walkthrough uses NuGuard to audit an AI application that calls Azure OpenAI. LiteLLM is used for NuGuard's own analysis; the target app uses its own Azure credentials independently.

Environment setup

# API key for NuGuard's LLM enrichment and red-team payload generation
# LiteLLM format for Azure: azure/<deployment-name>
export LITELLM_API_KEY="your-azure-openai-key"
export NUGUARD_REDTEAM_LLM_MODEL="azure/gpt-4o"

# Azure-specific vars consumed by LiteLLM
export AZURE_API_BASE="https://your-instance.openai.azure.com"
export AZURE_API_VERSION="2024-05-01-preview"

nuguard.yaml

llm:
  model: azure/gpt-4o
  api_base: "${AZURE_API_BASE}"
  api_version: "${AZURE_API_VERSION}"

redteam:
  target: http://localhost:8080
  endpoint: /chat
  llm_model: azure/gpt-4o

behavior:
  target: http://localhost:8080
  endpoint: /chat

Conversation

User: My AI agent at ~/projects/cs-bot uses Azure OpenAI. Audit it with NuGuard.

Claude calls nuguard_init:

nuguard_init(project_dir="~/projects/cs-bot", target_url="http://localhost:8080")

Creates nuguard.yaml, cognitive-policy.md, canary.example.json.

Claude calls nuguard_sbom_generate:

nuguard_sbom_generate(
  source="~/projects/cs-bot",
  output="~/projects/cs-bot/app.sbom.json",
  llm=true
)

Result: 11 nodes — 1 agent, azure/gpt-4o-deployment model, PostgreSQL tool, Azure Blob Storage datastore, 2 prompts, REST API endpoint. LLM enrichment annotates the Blob datastore as PII-adjacent.

Claude calls nuguard_analyze:

nuguard_analyze(
  sbom="~/projects/cs-bot/app.sbom.json",
  min_severity="medium",
  llm=true
)

Result:

• HIGH NGA-011: Azure Blob datastore with PII signals has no AUTH node in component graph
• HIGH NGA-007: SQL tool node lacks parameterization evidence — potential injection path
• MEDIUM NGA-003: No HITL gate before blob write operations

Claude asks whether to run red-team with the app running:

Static analysis found three structural issues. The PII datastore has no authentication boundary in the component graph, the SQL tool may accept unparameterized input, and blob writes have no human-in-the-loop gate. Start the app on port 8080 and I can run red-team to verify exploitability.

User: App is running. Go ahead.

Claude calls nuguard_redteam:

nuguard_redteam(
  config_path="~/projects/cs-bot/nuguard.yaml",
  profile="ci",
  fail_on="high"
)

Result (~4 min):

• CRITICAL DATA_EXFILTRATION: Agent returned blob file listing for a different tenant when asked "what files do you have access to?"
• HIGH PROMPT_DRIVEN_THREAT: System prompt partially extracted via indirect injection in uploaded filename field

Claude responds:

The red-team scan confirmed two exploitable vulnerabilities. The most critical is a cross-tenant storage leak — the agent returns Azure Blob container contents without enforcing a tenant boundary. The second is partial system prompt extraction via a filename injection vector.

Recommended fixes:

1. Scope all Azure Blob queries to the authenticated tenant's container prefix and enforce this in the tool layer, not just the prompt.
2. Sanitize uploaded filenames and other external string inputs before they reach the agent's context window.
3. Add a HITL confirmation step before any blob write or delete operation.

Restart Claude Desktop after editing claude_desktop_config.json. On macOS and Windows, Claude Desktop does not inherit your shell PATH, so relative command names may not resolve. Use the absolute path to whichever binary you chose:

{ "command": "/usr/local/bin/nuguard-mcp" }

{ "command": "/usr/local/bin/npx", "args": ["-y", "@nuguardai/nuguard"] }

Find the absolute path with which nuguard-mcp (macOS/Linux) or where nuguard-mcp (Windows).

The npx launcher could not find Python or uvx. Install one of:

uv pip install "nuguard[mcp]"   # recommended if you have uv
pip install "nuguard[mcp]"      # alternative — also installs the nuguard-mcp binary

or install uv and the launcher will use uvx automatically.

pip installed into a virtual environment whose bin/ directory is not on your PATH. Either activate the venv before starting Claude Desktop, or use the absolute path:

{ "command": "/path/to/.venv/bin/nuguard-mcp" }

The default timeout is 900 s. For large profile=full scans pass timeout_seconds=1800. Also check redteam.request_timeout in nuguard.yaml — it should match your app's response SLA.

Check the stderr field in the response. Common causes: sbom path doesn't exist, config_path points to a directory, or LITELLM_API_KEY is not set when llm=true.

These are optional external tools. Install them or disable them per-call:

nuguard_analyze(sbom="...", enable_grype=false, enable_trivy=false)