Skip to content
NINJA

Check an MCP server before you connect it

MCP Guard is a free, open-source command-line tool and agent skill. Point it at an MCP server (an npm or PyPI package, a Docker command, a local script or a remote URL) and it prints what it found: risky configuration, supply-chain warnings, suspicious package code and prompt injection hidden in tool descriptions. Then it gives a verdict: pass, warn or fail.

npx ninja-mcp-guard scan <package or https://url>

Needs Node.js 18 or later. Runs on your machine. Version 0.3.1, MIT licence, no dependencies. Source on GitHub

Poisoned tools: npx ninja-mcp-guard scan --probe -- node weather-server.mjs. Verdict FAIL, 4 fail · 5 warn. Hidden instructions in tool descriptions, caught before your agent ever reads them.

Hidden instructions in tool descriptions, caught before your agent ever reads them.

Add it to your agent

Claude Code, as a plugin

Installs the skill and the hooks in one step, and updates with the plugin.

/plugin marketplace add https://ninja.si/mcp-guard/marketplace.json
/plugin install ninja-mcp-guard@ninja-si

Claude Code, as a skill with hooks

npx ninja-mcp-guard install --hooks

With the hooks on, every MCP server you add is checked automatically, however you add it: with claude mcp add, by editing a config file or through a plugin. Each time Claude Code starts, servers that are new or whose config changed are checked and the verdict appears in the console. A server Claude adds is checked before it is added, and any server still unchecked is checked before its first tool call. A fail blocks it; a warning asks you first. Leave out --hooks for the skill alone.

The hooks also read what every MCP tool returns. An honest server can still hand your agent text an attacker wrote: an email, a GitHub issue, a web page. If a result contains instructions aimed at the AI, a warning is placed in front of it, so Claude treats it as untrusted data and tells you what it tried to do.

Other agents

Any agent that reads skills from a folder can use the same skill. Any agent that can run a shell command can call the tool directly.

npx ninja-mcp-guard install --dir <your agent's skills folder>

Claude on the web and desktop

Download the skill zip and upload it in Claude’s settings under Skills. Code execution must be on, and the live checks need network access to the server you are checking.

CI and scripts

npx ninja-mcp-guard scan --config .mcp.json --json --strict

Exits with 2 on a fail. With --strict, a warning exits with 1.

What to point it at

  • scan @scope/server@1.2.3an npm package
  • scan pypi:mcp-server-fetcha Python package run with uvx
  • scan https://example.com/mcpa remote server (connects and reads its tools)
  • scan -- npx -y some-server@1.2.3exactly the command your config runs
  • scan --allevery server in Claude Code, Claude Desktop, Cursor, VS Code and Windsurf configs

Local servers aren’t started unless you add --probe, because starting one runs its code. The probe gives it an empty, throwaway home folder and only the environment variables from its config. That keeps it away from your files and keys, but it isn’t a full sandbox: use a container or a spare machine for a package you don’t trust at all.

What it checks

Configuration
Shell command lines and curl-into-shell installs, unpinned package versions, Docker containers run privileged or with the Docker socket or your home folder mounted, unpinned images, remote servers over plain HTTP, credentials in URLs, and secrets stored in plain text.
Supply chain
Whether the package exists at all (a typo can point at an attacker’s package), look-alikes of popular MCP servers, package and release age, install-time scripts, deprecation, a linked source repository, npm provenance, download counts, and known vulnerabilities and malware reports from OSV.
Package code
Downloads the published package and reads it without running it: webhook and data-capture endpoints, encoded code passed to eval, scripts piped into a shell, access to SSH keys, credential stores and other agents’ MCP configs, environment dumps, hard-coded IP addresses, obfuscation and persistence.
Tools and prompts
Connects to the server and reads every tool, prompt and resource the model would see. Flags instructions to ignore the system prompt or hide things from you, tags like <IMPORTANT>, requests to read credential files or send secrets, invisible Unicode (decoded so you can read the hidden text), tools that try to change how other servers’ tools behave, and tools that can run commands, delete files, send messages or pay.
Tool results
Scans what tools return while you work: instructions to ignore the system prompt or hide things from you, hidden tags, invisible Unicode, requests to send secrets or the conversation somewhere, and text that addresses the AI directly. Results from every server are checked, including ones you trust.
Rug pulls
Saves a fingerprint of every tool after each live check. If a server quietly changes its tool descriptions later, the next check names the tools that changed.

What a pass means

A pass means none of the known warning signs turned up. It does not prove a server is safe. Patterns can be evaded, the package’s dependencies aren’t audited, container images aren’t opened, and a server can behave differently once it is running and you call its tools.

Treat a fail as stop, a warning as something to read, and a pass as nothing obvious. If a server you rely on fails for a reason you understand and accept, ninja-mcp-guard approve <server> records that, and the hooks stop blocking it.

Privacy

Everything runs on your machine. To check a server it contacts the npm and PyPI registries, the OSV vulnerability database and the server itself. Nothing is sent to ninja.si, and the tool keeps no record of what you scan beyond the verdicts and fingerprints in ~/.ninja-mcp-guard on your machine.

Open source, verified builds

The full source is on GitHub. Every release is built and published by GitHub Actions, and npm attaches a signed provenance statement that ties the package to the exact commit it was built from. You can check it on the npm page or with npm audit signatures. Found a way around it? Report it privately through the repository’s security tab.

Downloads

The npm package is the same file. To install it straight from here: npm install -g https://ninja.si/mcp-guard/ninja-mcp-guard-0.3.1.tgz