{"id":27477109,"url":"https://github.com/invariantlabs-ai/mcp-scan","last_synced_at":"2026-01-28T11:00:46.434Z","repository":{"id":287241537,"uuid":"962024783","full_name":"invariantlabs-ai/mcp-scan","owner":"invariantlabs-ai","description":"Constrain, log and scan your MCP connections for security vulnerabilities.","archived":false,"fork":false,"pushed_at":"2026-01-20T16:30:16.000Z","size":1349,"stargazers_count":1404,"open_issues_count":12,"forks_count":138,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-01-20T21:45:07.964Z","etag":null,"topics":["agent","ai","mcp","modelcontextprotocol","security"],"latest_commit_sha":null,"homepage":"https://invariantlabs.ai/blog/introducing-mcp-scan","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/invariantlabs-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-07T14:31:26.000Z","updated_at":"2026-01-20T20:45:32.000Z","dependencies_parsed_at":"2025-05-05T09:51:24.516Z","dependency_job_id":"1656ed33-3727-4420-b749-228466363ac6","html_url":"https://github.com/invariantlabs-ai/mcp-scan","commit_stats":null,"previous_names":["invariantlabs-ai/mcp-scan"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/invariantlabs-ai/mcp-scan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invariantlabs-ai%2Fmcp-scan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invariantlabs-ai%2Fmcp-scan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invariantlabs-ai%2Fmcp-scan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invariantlabs-ai%2Fmcp-scan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/invariantlabs-ai","download_url":"https://codeload.github.com/invariantlabs-ai/mcp-scan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invariantlabs-ai%2Fmcp-scan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28844406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T10:53:21.605Z","status":"ssl_error","status_checked_at":"2026-01-28T10:53:20.789Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","mcp","modelcontextprotocol","security"],"created_at":"2025-04-16T08:04:06.468Z","updated_at":"2026-01-28T11:00:46.422Z","avatar_url":"https://github.com/invariantlabs-ai.png","language":"Python","funding_links":[],"categories":["漏洞扫描","Development","[↑](#table-of-contents)Tools \u003ca name=\"tools\"\u003e\u003c/a\u003e","Python","📚 Projects (1974 total)","🧑‍🚀 Tools and code","🤖 AI/ML","MCP Security (Model Context Protocol)","Defense \u0026 Security Controls","Model Context Protocol (MCP)","Agent Security","🔌 MCP Security","カテゴリ","Tools \u0026 Frameworks","MCP Ecosystem","🏗️ Infrastructure, Utils \u0026 Orchestration","Online Tutorials / Blogs / Presentations","MCP Servers"],"sub_categories":["MCP Servers/Tools","Agent Tooling and MCP Security","MCP Servers","Security Tools \u0026 Frameworks","MCP Security","Scanners and Auditors","🔒 \u003ca name=\"security--auth\"\u003e\u003c/a\u003eセキュリティ・認証","Security Testing","Servers","🛡️ Security Operations (Blue/Purple)","MCP \u0026 Agent Security","Security \u0026 Reverse Engineering"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e\n  mcp-scan\n  \u003c/h1\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  MCP security scanning tool for local and remote MCP Servers\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.python.org/pypi/mcp-scan\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/mcp-scan.svg\" alt=\"mcp-scan\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.python.org/pypi/mcp-scan\"\u003e\u003cimg src=\"https://img.shields.io/pypi/l/mcp-scan.svg\" alt=\"mcp-scan license\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.python.org/pypi/mcp-scan\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/mcp-scan.svg\" alt=\"mcp-scan python version requirements\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\".github/mcp-scan-cmd-banner.png?raw=true\" alt=\"MCP-Scan logo\"/\u003e\n\u003c/div\u003e\n\n## Highlights\n\n- Auto-discover MCP configurations\n- Detects MCP Security Vulnerabilities:\n  - Prompt Injection Attacks\n  - Tool Poisoning Attacks\n  - Toxic Flows\n- Scan local STDIO MCP Servers\n- Scan remote HTTP/SSE MCP Servers\n\n## Quick Start\n\n### MCP Server Scanning\n\nTo run an MCP scan:\n\n```bash\nuvx mcp-scan@latest\n```\n\nThis will scan your installed servers for security vulnerabilities in tools, prompts, and resources. It will automatically discover a variety of MCP configurations, including Claude, Cursor and Windsurf.\n\nTo scan a particular MCP server configuration, for example, a VS Code MCP config, you can run:\n\n```bash\nmcp-scan ~/.vscode/mcp.json\n```\n\n#### Example Run\n[![MCP Scan for security vulnerabilities demo](demo.svg)](https://asciinema.org/a/716858)\n\n\n## MCP Security Scanner Capabilities\n\nMCP-Scan is a security scanning tool to both statically and dynamically scan and monitor your MCP connections. It checks them for common security vulnerabilities like [prompt injections](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks), [tool poisoning](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks) and [toxic flows](https://invariantlabs.ai/blog/mcp-github-vulnerability). Consult our detailed [Documentation](https://invariantlabs-ai.github.io/docs/mcp-scan) for more information.\n\nMCp-Scan operates in two main modes which can be used jointly or separately:\n\n1. `mcp-scan scan` statically scans all your installed servers for malicious tool descriptions and tools (e.g. [tool poisoning attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks), cross-origin escalation, rug pull attacks, toxic flows).\n\n    [Quickstart →](#server-scanning).\n\n2. `mcp-scan proxy` continuously monitors your MCP connections in real-time, and can restrict what agent systems can do over MCP (tool call checking, data flow constraints, PII detection, indirect prompt injection etc.).\n\n    [Quickstart →](#server-proxying).\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://invariantlabs-ai.github.io/docs/mcp-scan/assets/proxy.svg\" width=\"420pt\" align=\"center\"/\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n_mcp-scan in proxy mode._\n\n\u003c/div\u003e\n\n## Features\n\n- Scanning of Claude, Cursor, Windsurf, and other file-based MCP client configurations\n- Scanning for prompt injection attacks in tools and [tool poisoning attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks) using [Guardrails](https://github.com/invariantlabs-ai/invariant?tab=readme-ov-file#analyzer)\n- [Enforce guardrailing policies](https://invariantlabs-ai.github.io/docs/mcp-scan/guardrails-reference/) on MCP tool calls and responses, including PII detection, secrets detection, tool restrictions and entirely custom guardrailing policies.\n- Audit and log MCP traffic in real-time via [`mcp-scan proxy`](#proxy)\n- Detect cross-origin escalation attacks (e.g. [tool shadowing](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)), and detect and prevent [MCP rug pull attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks), i.e. mcp-scan detects changes to MCP tools via hashing\n\n\n\n### Server Proxying\n\nUsing `mcp-scan proxy`, you can monitor, log, and safeguard all MCP traffic on your machine. This allows you to inspect the runtime behavior of agents and tools, and prevent attacks from e.g., untrusted sources (like websites or emails) that may try to exploit your agents. mcp-scan proxy is a dynamic security layer that runs in the background, and continuously monitors your MCP traffic.\n\n#### Example Run\n\n\u003cimg width=\"903\" alt=\"image\" src=\"https://github.com/user-attachments/assets/63ac9632-8663-40c3-a765-0bfdfbdf9a16\" /\u003e\n\n#### Enforcing Guardrails\n\nYou can also add guardrailing rules, to restrict and validate the sequence of tool uses passing through proxy.\n\nFor this, create a `~/.mcp-scan/guardrails_config.yml` with the following contents:\n\n```yml\n\u003cclient-name\u003e:  # your client's shorthand (e.g., cursor, claude, windsurf)\n  \u003cserver-name\u003e:  # your server's name according to the mcp config (e.g., whatsapp-mcp)\n    guardrails:\n      secrets: block # block calls/results with secrets\n\n      custom_guardrails:\n        - name: \"Filter tool results with 'error'\"\n          id: \"error_filter_guardrail\"\n          action: block # or just 'log'\n          content: |\n            raise \"An error was found.\" if:\n              (msg: ToolOutput)\n              \"error\" in msg.content\n```\nFrom then on, all calls proxied via `mcp-scan proxy` will be checked against your configured guardrailing rules for the current client/server.\n\nCustom guardrails are implemented using Invariant Guardrails. To learn more about these rules, see the [official documentation](https://invariantlabs-ai.github.io/docs/mcp-scan/guardrails-reference/).\n\n## How It Works\n\n### Scanning\n\nMCP-Scan `scan` searches through your configuration files to find MCP server configurations. It connects to these servers and retrieves tool descriptions.\n\nIt then scans tool descriptions, both with local checks and by invoking Invariant Guardrailing via an API. For this, tool names and descriptions are shared with invariantlabs.ai. By using MCP-Scan, you agree to the invariantlabs.ai [terms of use](./TERMS.md) and [privacy policy](https://invariantlabs.ai/privacy-policy).\n\nInvariant Labs is collecting data for security research purposes (only about tool descriptions and how they change over time, not your user data). Don't use MCP-scan if you don't want to share your tools. Additionally, a unique, persistent, and anonymous ID is assigned to your scans for analysis. You can opt out of sending this information using the `--opt-out` flag.\n\nMCP-scan does not store or log any usage data, i.e. the contents and results of your MCP tool calls.\n\n### Proxying\n\nFor runtime monitoring using `mcp-scan proxy`, MCP-Scan can be used as a proxy server. This allows you to monitor and guardrail system-wide MCP traffic in real-time. To do this, mcp-scan temporarily injects a local [Invariant Gateway](https://github.com/invariantlabs-ai/invariant-gateway) into MCP server configurations, which intercepts and analyzes traffic. After the `proxy` command exits, Gateway is removed from the configurations.\n\nYou can also configure guardrailing rules for the proxy to enforce security policies on the fly. This includes PII detection, secrets detection, tool restrictions, and custom guardrailing policies. Guardrails and proxying operate entirely locally using [Guardrails](https://github.com/invariantlabs-ai/invariant) and do not require any external API calls.\n\n## CLI parameters\n\nMCP-scan provides the following commands:\n\n```\nmcp-scan - Security scanner for Model Context Protocol servers and tools\n```\n\n### Common Options\n\nThese options are available for all commands:\n\n```\n--storage-file FILE    Path to store scan results and whitelist information (default: ~/.mcp-scan)\n--base-url URL         Base URL for the verification server\n--verbose              Enable detailed logging output\n--print-errors         Show error details and tracebacks\n--full-toxic-flows     Show all tools that could take part in toxic flow. By default only the top 3 are shown.\n--json                 Output results in JSON format instead of rich text\n```\n\n### Commands\n\n#### scan (default)\n\nScan MCP configurations for security vulnerabilities in tools, prompts, and resources.\n\n```\nmcp-scan [CONFIG_FILE...]\n```\n\nOptions:\n```\n--checks-per-server NUM       Number of checks to perform on each server (default: 1)\n--server-timeout SECONDS      Seconds to wait before timing out server connections (default: 10)\n--suppress-mcpserver-io BOOL  Suppress stdout/stderr from MCP servers (default: True)\n```\n\n#### proxy\n\nRun a proxy server to monitor and guardrail system-wide MCP traffic in real-time. Temporarily injects [Gateway](https://github.com/invariantlabs-ai/invariant-gateway) into MCP server configurations, to intercept and analyze traffic. Removes Gateway again after the `proxy` command exits.\n\nThis command requires the `proxy` optional dependency (extra).\n\n- Run via uvx:\n  ```bash\n  uvx --with \"mcp-scan[proxy]\" mcp-scan@latest proxy\n  ```\n  This installs the `proxy` extra into an uvx-managed virtual environment, not your current shell venv.\n\nOptions:\n```\nCONFIG_FILE...                  Path to MCP configuration files to setup for proxying.\n--pretty oneline|compact|full   Pretty print the output in different formats (default: compact)\n```\n\n\n#### inspect\n\nPrint descriptions of tools, prompts, and resources without verification.\n\n```\nmcp-scan inspect [CONFIG_FILE...]\n```\n\nOptions:\n```\n--server-timeout SECONDS      Seconds to wait before timing out server connections (default: 10)\n--suppress-mcpserver-io BOOL  Suppress stdout/stderr from MCP servers (default: True)\n```\n\n#### whitelist\n\nManage the whitelist of approved entities. When no arguments are provided, this command displays the current whitelist.\n\n```\n# View the whitelist\nmcp-scan whitelist\n\n# Add to whitelist\nmcp-scan whitelist TYPE NAME HASH\n\n# Reset the whitelist\nmcp-scan whitelist --reset\n```\n\nOptions:\n```\n--reset                       Reset the entire whitelist\n--local-only                  Only update local whitelist, don't contribute to global whitelist\n```\n\nArguments:\n```\nTYPE                          Type of entity to whitelist: \"tool\", \"prompt\", or \"resource\"\nNAME                          Name of the entity to whitelist\nHASH                          Hash of the entity to whitelist\n```\n\n#### help\n\nDisplay detailed help information and examples.\n\n```bash\nmcp-scan help\n```\n\n### Examples\n\n```bash\n# Scan all known MCP configs\nmcp-scan\n\n# Scan a specific config file\nmcp-scan ~/custom/config.json\n\n# Just inspect tools without verification\nmcp-scan inspect\n\n# View whitelisted tools\nmcp-scan whitelist\n\n# Whitelist a tool\nmcp-scan whitelist tool \"add\" \"a1b2c3...\"\n```\n\n## Demo\n\nThis repository includes a vulnerable MCP server that can demonstrate Model Context Protocol security issues that MCP-Scan finds.\n\nHow to demo MCP security issues?\n1. Clone this repository\n2. Create an `mcp.json` config file in the cloned git repository root directory with the following contents:\n```jsonc\n{\n  \"mcpServers\": {\n    \"Demo MCP Server\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"mcp\", \"run\", \"demoserver/server.py\"],\n    }\n  }\n}\n```\n3. Run MCP-Scan: `uvx --python 3.13 mcp-scan@latest scan --full-toxic-flows mcp.json`\n\nNote: if you place the `mcp.json` configuration filepath elsewhere then adjust the `args` path inside the MCP server configuration to reflect the path to the MCP Server (`demoserver/server.py`) as well as the `uvx` command that runs MCP-Scan CLI with the correct filepath to `mcp.json`.\n\n## MCP-Scan is closed to contributions\n\nMCP-Scan can currently no longer accept external contributions. We are focused on stabilizing releases.\nWe welcome suggestions, bug reports, or feature requests as GitHub issues.\n\n## Development Setup\n\nTo run this package from source, follow these steps:\n\n```bash\nuv run pip install -e .\nuv run -m src.mcp_scan.cli\n```\n\nFor proxy functionality (e.g., `mcp-scan proxy`, `mcp-scan server`), install with the proxy extra:\n\n```bash\nuv run pip install -e .[proxy]\n```\n\n## Including MCP-scan results in your own project / registry\n\nIf you want to include MCP-scan results in your own project or registry, please reach out to the team via `mcpscan@invariantlabs.ai`, and we can help you with that.\nFor automated scanning we recommend using the `--json` flag and parsing the output.\n\n## Further Reading\n\n- [Introducing MCP-Scan](https://invariantlabs.ai/blog/introducing-mcp-scan)\n- [MCP Security Notification Tool Poisoning Attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)\n- [WhatsApp MCP Exploited](https://invariantlabs.ai/blog/whatsapp-mcp-exploited)\n- [MCP Prompt Injection](https://simonwillison.net/2025/Apr/9/mcp-prompt-injection/)\n- [Toxic Flow Analysis](https://invariantlabs.ai/blog/toxic-flow-analysis)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finvariantlabs-ai%2Fmcp-scan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finvariantlabs-ai%2Fmcp-scan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finvariantlabs-ai%2Fmcp-scan/lists"}