Çeşitli yapılandırma dosyaları ve canlı süreçler üzerinden tarama yaparak yerel MCP server yapılarını envanterler ve risk derecelendirmesi yapar.
Ayrıca bilinen adı saagpatel/shadow-mcp
- Yıldızlar
- 0
- Araçlar
- 4
- İndirmeler, 30 gün
- 100
- En son sürüm
- 0.2.0
- Son commit
- 14 Kas 2026
- Lisans
- —
shadow MCP nedir?
shadow bir MCP sunucusudur. Çeşitli yapılandırma dosyaları ve canlı süreçler üzerinden tarama yaparak yerel MCP server yapılarını envanterler ve risk derecelendirmesi yapar. 4 araç sunar; örneğin scan_local, discover_local, deep_scan.
Özet, projenin README dosyasından oluşturuldu
shadow MCP sunucusu hakkında
Güvenlik araştırmacıları ve geliştiriciler, yerel bir makinede çalışan MCP server yapılarının güvenlik durumunu belirlemek ve değerlendirmek için shadow-mcp kullanabilirler. Bu araç; Claude Code, Claude Desktop, Codex, projeye özel .mcp.json dosyaları ve bir porta bağlanmayan canlı süreçler arasında dağınık halde bulunan yapılandırmaları bularak shadow MCP server sorununu çözer. Araç, farklı kaynaklardan gelen bulguları yerel ortamınızın tek bir mantıksal görünümünde birleştirerek eksiksiz bir envanter sunar.
Keşif aşamasından sonra sistem; yetenek ve enjeksiyon bulguları için MCPAudit, tehlike derecelendirmeleri için ise mcp-trust gibi uzmanlaşmış motorlara görev devrederek risk dereceleri atar. Kullanıcılar, yapılandırma dosyalarına dayalı statik bir tarama gerçekleştirebilir veya gerçek araçları listelemek için stdio server yapılarını fiilen başlatan bağlantılı bir derin tarama (deep-scan) seçeneğini tercih edebilirler. Sonuçlar; yapılandırılmış ve çalışan serverlar arasındaki tutarsızlıkları vurgulayarak terminal tabloları, makine tarafından okunabilir JSON veya markdown raporları aracılığıyla sunulur.
Neler yapabilirsiniz
- 1Yerel server yapılandırmalarını denetleyinMakinenizdeki çeşitli yapılandırma dosyalarında ve aktif süreçlerde gizlenmiş tüm MCP server yapılarını tespit edin.
- 2Gerçek araç yeteneklerini değerlendirinServerlara bağlanarak gerçek fonksiyonel izinlerini görmek için derin tarama gerçekleştirin.
- 3Makine tarafından okunabilir güvenlik envanterleri oluşturunOtomatik işleme tabi tutmak üzere yerel MCP yüzeyinizin tam envanterini bir JSON dosyası olarak dışa aktarın.
- 4Shadow server varlığını izleyinŞu anda çalışan ancak standart yapılandırma dosyalarınızda belgelenmemiş server yapılarını tespit edin.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
shadow MCP nasıl yüklenir
Biçimler 10 Kas 2026 tarihinde doğrulandıCursor'a ekleGoose'a ekleshadow MCP'yi Claude Code içine yükleyin
$ claude mcp add shadow-mcp -- uvx shadow-mcpshadow MCP'yi Cursor içine yükleyin
~/.cursor/mcp.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP'yi VS Code içine yükleyin
.vscode/mcp.json
{
"servers": {
"shadow-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP'yi VS Code CLI içine yükleyin
$ code --add-mcp '{"name":"shadow-mcp","type":"stdio","command":"uvx","args":["shadow-mcp"]}'shadow MCP'yi Claude Desktop içine yükleyin
claude_desktop_config.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP'yi Codex içine yükleyin
$ codex mcp add shadow-mcp -- uvx shadow-mcpshadow MCP'yi Codex config.toml içine yükleyin
~/.codex/config.toml
[mcp_servers.shadow-mcp] command = "uvx" args = ["shadow-mcp"]
shadow MCP'yi Gemini CLI içine yükleyin
$ gemini mcp add -s user shadow-mcp uvx -- shadow-mcpshadow MCP'yi Gemini settings.json içine yükleyin
~/.gemini/settings.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP araçları 4
README dosyasından algılandıscan_localdiscover_localdeep_scanlist_sources
| scan_local | — | |
| discover_local | — | |
| deep_scan | — | |
| list_sources | — |
Otomatik kontroller
Çalıştırıldı 14 Kas 2026Tam rapor →Otomatik kontrollerimizden geçti. Bu bir güvenlik denetimi değildir: kodu okuyun ve sunucuya ihtiyaç duyduğu en dar erişimi verin. Kontroller nasıl çalışır · Daha fazla puan için nelerin düzeltileceği
- Kaynak deposu bağlantılı ve erişilebilirsaagpatel/shadow-mcp is public and reachablegithub.com/saagpatel/shadow-mcp ↗Geçti
- Paket, bu depoyu kaynağı olarak gösteriyorKontrol edilmedi
- Derleme kökeni (Sigstore onayı)Sigstore attestation for shadow-mcppypi.org/project/shadow-mcp/ ↗Geçti
- Açık kaynak lisansı (OSI)No licenseBulgu
- Son bir yıl içinde commit veya sürüm mevcutLast commit or release 2026-11-08github.com/saagpatel/shadow-mcp ↗Geçti
- OpenSSF ScorecardKontrol edilmedi
- Paket adı popüler bir pakete yakın değilNo popular package one edit away from shadow-mcpGeçti
- Pakette veya bağımlılıklarında kritik uyarı yok43 resolved dependencies checked; no critical advisoryosv.dev ↗Geçti
- Modele yönelik gizli talimat yok4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersGeçti
- Yıkıcı araçlar etiketlenmişNo tool named like delete, drop or execGeçti
- Uzak uç nokta MCP el sıkışmasına yanıt veriyorKontrol edilmedi
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 soruları
shadow MCP'yi Claude Code'a nasıl eklerim?
Terminalinizde claude mcp add shadow-mcp -- uvx shadow-mcp komutunu çalıştırın. Her projede kullanılabilir olması için --scope user ekleyin.
shadow MCP'yi Cursor'a nasıl eklerim?
~/.cursor/mcp.json dosyasını açın ve yukarıdaki yükleme bölümünde gösterilen Cursor yapılandırmasını kullanarak sunucuyu mcpServers altına ekleyin.
shadow MCP hangi araçları sunar?
4 araç sunar; bunlar arasında scan_local, discover_local, deep_scan, list_sources yer alır.
shadow-mcp ne işe yarar?
Yapılandırma dosyalarını ve canlı süreçleri tarayarak makinenizde bulunan MCP server yapılarını keşfeder, envanterini çıkarır ve risk derecelendirmesi yapar.
Keşif süreci güvenli mi?
Evet, keşif süreci salt okunur (read-only) çalışır; toplayıcılar, bulunan hiçbir şeyi değiştirmeden yapılandırmaları ayrıştırır ve süreçleri listeler.
Gizli bilgileri (secrets) nasıl yönetir?
Potansiyel gizli bilgileri işaretlemek için ortam değişkeni (environment variable) isimlerini kaydeder ancak gerçek değerleri asla kaydetmez ve satır içi kimlik bilgilerini maskeler.