다양한 설정 파일과 실행 중인 프로세스를 탐색하여 로컬 MCP server를 인벤토리화하고 위험 등급을 분류합니다.
다른 이름 saagpatel/shadow-mcp
- 스타
- 0
- Tools
- 4
- 다운로드, 30일
- 100
- 최신 버전
- 0.2.0
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- —
shadow MCP란?
shadow은(는) MCP server입니다. 다양한 설정 파일과 실행 중인 프로세스를 탐색하여 로컬 MCP server를 인벤토리화하고 위험 등급을 분류합니다. 4개 도구를 제공합니다. 예: scan_local, discover_local, deep_scan.
프로젝트 README에서 생성된 요약
shadow MCP server 정보
보안 연구자와 개발자는 shadow-mcp를 사용하여 로컬 머신에서 실행 중인 MCP server의 보안 상태를 식별하고 평가할 수 있습니다. 이 도구는 Claude Code, Claude Desktop, Codex, 프로젝트별 .mcp.json 파일에 흩어져 있는 설정과 포트에 바인딩되지 않은 실행 프로세스를 찾아내어 shadow MCP server 문제를 해결합니다. 서로 다른 소스에서 발견된 정보를 하나의 논리적인 로컬 환경 뷰로 병합하여 완전한 인벤토리를 제공합니다.
탐색 후 시스템은 권한 및 인젝션 탐지를 위한 MCPAudit와 위험 등급 판정을 위한 mcp-trust 같은 전문 엔진에 작업을 위임하여 위험 등급을 할당합니다. 사용자는 설정 파일을 기반으로 정적 스캔을 수행하거나, 실제 stdio server를 실행하여 실제 도구를 열거하는 연결형 딥 스캔(deep-scan)을 선택할 수 있습니다. 결과는 터미널 테이블, 기계 판독 가능한 JSON 또는 markdown 보고서로 제공되며, 설정된 서버와 실행 중인 서버 간의 불일치를 강조하여 보여줍니다.
활용 사례
- 1로컬 서버 설정 감사머신의 다양한 설정 파일과 활성 프로세스에 숨겨진 모든 MCP server를 식별합니다.
- 2실제 도구 권한 평가서버에 연결하여 실제 기능적 권한을 확인하는 딥 스캔을 수행합니다.
- 3기계 판독 가능한 보안 인벤토리 생성자동화된 처리를 위해 로컬 MCP 접점의 전체 인벤토리를 JSON 파일로 내보냅니다.
- 4shadow server 존재 여부 모니터링현재 실행 중이지만 표준 설정 파일에는 기록되지 않은 서버를 탐지합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
shadow MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 shadow MCP 설치
$ claude mcp add shadow-mcp -- uvx shadow-mcpCursor에 shadow MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}VS Code에 shadow MCP 설치
.vscode/mcp.json
{
"servers": {
"shadow-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}VS Code CLI에 shadow MCP 설치
$ code --add-mcp '{"name":"shadow-mcp","type":"stdio","command":"uvx","args":["shadow-mcp"]}'Claude Desktop에 shadow MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}Codex에 shadow MCP 설치
$ codex mcp add shadow-mcp -- uvx shadow-mcpCodex config.toml에 shadow MCP 설치
~/.codex/config.toml
[mcp_servers.shadow-mcp] command = "uvx" args = ["shadow-mcp"]
Gemini CLI에 shadow MCP 설치
$ gemini mcp add -s user shadow-mcp uvx -- shadow-mcpGemini settings.json에 shadow MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP 도구 4
README에서 감지됨scan_localdiscover_localdeep_scanlist_sources
| scan_local | — | |
| discover_local | — | |
| deep_scan | — | |
| list_sources | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능saagpatel/shadow-mcp is public and reachablegithub.com/saagpatel/shadow-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)Sigstore attestation for shadow-mcppypi.org/project/shadow-mcp/ ↗통과
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-08github.com/saagpatel/shadow-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from shadow-mcp통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음43 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음4 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기shadow-mcp
Discover and risk-grade the MCP servers actually present on this machine.
Most MCP security tooling assumes you already have a list of servers to audit.
On a real developer machine you don't: servers are scattered across Claude Code,
Codex, Claude Desktop, project-local .mcp.json files, DXT extensions, and live
processes that bind no port. shadow-mcp finds them first, then grades them.
This is the local-first answer to OWASP MCP09:2025 — Shadow MCP Servers.
What it does
discover -> inventory -> risk-grade -> report
- Discover (read-only) MCP servers from supported configuration and runtime sources:
Claude Code (
~/.claude.json, user + project scope),claude mcp list(catches remote + plugin servers no file contains), Codex (~/.codex/config.toml+ profiles), project.mcp.json, Claude Desktop config + DXT extension manifests, and the live process table. - Inventory: merge sightings into one entry per logical server, even when a
server appears under different names across hosts (
personal-opsvspersonal_ops), tracking every provenance. - Risk-grade by delegating to the existing engines rather than reimplementing them:
- Report: a ranked terminal table, a machine-readable JSON inventory, or markdown — plus a Shadow & attention section for the deltas that matter (running-but-unconfigured, broad blast radius, capable-but-ungraded).
The risk model and its OWASP mapping live in docs/risk-model.md.
Install
From this repository root, use uv:
make setup
The grading engines (mcp-audits and mcp-trust) are runtime dependencies
resolved from PyPI, not editable sibling checkouts or an engines group.
The installed mcp-trust package supplies its seed catalog; --registry-db or
SHADOW_MCP_MCPTRUST_DB selects an explicitly chosen local registry instead.
Use
uv run shadow-mcp scan # full pipeline, terminal report
uv run shadow-mcp scan --json out.json # machine-readable inventory
uv run shadow-mcp scan --format markdown # markdown report
uv run shadow-mcp discover # inventory only, no grading
uv run shadow-mcp sources # per-collector counts
uv run shadow-mcp grade-missing # A-F for servers the registry hasn't scanned
uv run shadow-mcp deep-scan cost-tracker # connect to a server, grade its real tools
Useful flags: --no-processes (skip the live process scan), --no-cli (skip
claude mcp list), --no-mcpaudit (inventory + mcp-trust only), --home PATH
(point discovery at a fixture tree).
Static vs connected grading
By default grading is static (config-only): no server is spawned, so grades reflect what's visible in the config. That's safe but coarse — a server's real capability only shows once you connect and list its tools.
shadow-mcp scan --connect (or deep-scan [names...]) spawns each stdio
server and enumerates its real tools, delegating to MCPAudit's connected engine
for a capability grade that actually differentiates (a filesystem server jumps
from a static A to a connected D). This is opt-in because connecting
executes the server; remote endpoints are never spawned (that's the network-scan
tier), and a server that needs real secrets to start falls back to its static
grade.
Development and safe verification
The committed uv.lock fixes the PyPI runtime and development graph. From the
repository root, run:
make check
The suite uses synthetic homes. Keep SHADOW_MCP_RUN_CONNECT unset: the
explicitly opted-in connected test is a separate server-execution lane. CI runs
the same aggregate gate on Python 3.11 through 3.15; see
the workflow. make build creates the wheel and
sdist used by the release workflow.
Do not use the normal scan, discover, sources, grade-missing or MCP tool
calls as a development smoke: they inventory the machine by default. CLI
deep-scan and scan --connect additionally execute servers. For changed JSON
or Markdown reports, check the corresponding fixture tests (tests/test_report.py)
and inspect synthetic output; this CLI has no browser UI. Actual workstation or
connected behavior requires its own explicitly authorized qualification.
Safety
- Read-only discovery. Collectors parse configs, invoke
claude mcp list(unless--no-cliis set), and list processes; nothing they find is ever mutated. (--connect/deep-scanis the one path that executes servers, and only when you explicitly ask.) - Secrets stay out. We record env variable names (to flag secret-bearing
servers per MCP01) but never their values. Inline credentials in command
arguments, URLs, and process parent commands are redacted before storage. A
captured inventory still contains local paths and hostnames, so treat
*.inventory.jsonas private (it is git-ignored by default).
Use as an MCP server
shadow-mcp can serve its own inventory tools as an MCP server so an agent can query your local MCP surface without leaving the conversation.
Tools
| Tool | Description |
|---|---|
scan_local |
Full pipeline (discover → inventory → grade → report). Returns JSON. |
discover_local |
Inventory every MCP server without grading. Returns JSON. |
deep_scan |
Grade the named servers, or all servers when the list is empty (static, no spawning). Accepts names: list[str]. Returns JSON. |
list_sources |
Per-collector source counts from a discover run. Returns JSON. |
Run the server
# directly from a local checkout
uv run shadow-mcp mcp-serve
# via uvx (once published to PyPI)
uvx shadow-mcp mcp-serve
LOCAL only. MCP tools read local configs and the process table, skip
claude mcp list, and never connect to hosted MCP endpoints or spawn servers.
Grading is static (config-based); connect=False is enforced unconditionally.
Scope
This is the local-first tool: it inventories one machine from its configs
and processes. A later network-scan expansion (probing hosts/ports for remote
MCP endpoints, org-wide fleet inventory, typosquat-distance provenance checks)
is deliberately out of scope here — see the bottom of docs/risk-model.md and
the project notes for what that would add.
Status
Stack
Python 3.11+; uv-managed locked dependencies; Ruff, mypy, and pytest checks; Hatchling wheel and sdist builds.
Known risks
- The minimum Python version remains 3.11 pending an owner decision about raising it to 3.12.
- The MCP tool name
deep_scanremains unchanged pending an owner decision; the similarly named CLI command can connect to servers. - Identity collisions in identity and inventory matching.
- Process sightings are deduplicated by name before owner classification.
- Grading evidence is limited to eight findings, and
criticalranks belowlow. - Collector failures can be silent.
--jsonis ignored bysourcesandgrade-missing.- Report writes are not atomic.
- Markdown and Rich output escaping differs.
- Dependency major upgrades, moving off Hatchling, a coverage threshold, package publishing, tags, and releases remain out of scope.
Next steps
Resolve the Python floor and MCP tool naming decisions, then address the listed behavior risks in a follow-up wave.
shadow MCP 질문
shadow MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add shadow-mcp -- uvx shadow-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
shadow MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
shadow MCP는 어떤 도구를 제공하나요?
4개 도구를 제공합니다. 예: scan_local, discover_local, deep_scan, list_sources.
shadow-mcp는 무엇을 하나요?
설정 파일과 실행 중인 프로세스를 스캔하여 사용자의 머신에 존재하는 MCP server를 발견하고, 인벤토리를 작성하며, 위험 등급을 분류합니다.
탐색 과정은 안전한가요?
네, 탐색은 읽기 전용으로 진행됩니다. 수집기(collector)는 발견된 항목을 변경하지 않고 설정 파일을 파싱하거나 프로세스 목록을 나열합니다.
비밀 정보는 어떻게 처리하나요?
잠재적인 비밀 정보가 포함된 환경 변수 이름은 기록하여 표시하지만, 실제 값은 절대 기록하지 않으며 인라인 자격 증명은 마스킹 처리합니다.