kerlenton/mcpsnoopWireshark для MCP. Прозрачный прокси между вашим AI-клиентом и MCP-сервером. Наблюдайте за каждым вызовом в реальном времени в терминале, проваливайте CI на основе обнаруженного, экспортируйте спаны OpenTelemetry.
<p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/9109/91d664ea266713affb29238906792777021b43fa6627b13f46382f48ad340a61.png" alt="mcpsnoop" width="440"> </p> **Wireshark для MCP.** mcpsnoop находится между вашим AI-клиентом и вашим MCP-сервером и записывает каждый JSON-RPC кадр, которым они обмениваются, без изменений с обеих сторон. Наблюдайте за ним в реальном времени в терминале, проваливайте CI на основе найденного или отправляйте его в ваш бэкенд трассировки в виде OpenTelemetry-спанов. [](https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/kerlenton/mcpsnoop) [](LICENSE) [](https://github.com/marketplace/actions/mcpsnoop) <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/9109/30466d77be15250e4bab6639e48a4cd5b0d44cd96e48606b60c6bacb67c15c3d.gif" alt="демонстрация mcpsnoop"> </p> ## Проблема Официальный [MCP Inspector](https://github.com/modelcontextprotocol/inspector) подключается как собственный клиент, поэтому он никогда не видит, что *ваш* клиент (Cursor, Claude Code, Codex) на самом деле отправляет вашему серверу. А всё, что ждёт поступления запроса, не может показать вызов, который модель так и не сделала или сделала с неправильными аргументами. Когда инструмент молча не вызывается, возможности не совпадают или вызов просто зависает, вам остаётся копаться в логах и гадать. **Вместо этого mcpsnoop находится в реальном пути данных.** Оберните команду вашего сервера им и наблюдайте за каждым JSON-RPC кадром в реальном времени, пока ваш настоящий клиент и сервер общаются. ## В CI Эта страница также является листингом для [mcpsnoop GitHub Action](https://github.com/marketplace/actions/mcpsnoop), поэтому вот он целиком. Он проверяет записанную сессию, регистрирует каждую находку как оповещение сканирования кода и проваливает задание на основе того, что вы задали в качестве условия. ```yaml permissions: security-events: write contents: read steps: - uses: kerlenton/[email protected] with: session: artifacts/session.jsonl ``` Нет захвата под рукой? Запишите одну сессию своим клиентом один раз, закоммитьте её, и пусть действие воспроизводит её против каждой сборки. Ни модель, ни API-ключ не запускаются в CI. Воспроизведение проверяется так же, как любой захват, и задание также завершается с ошибкой, когда сервер стал хуже, чем в записи. Сервер, доступный через Streamable HTTP, получает `target` со своей конечной точкой, а запись воспроизводится через любой из транспортов. ```yaml steps: - uses: kerlenton/[email protected] with: replay: tests/mcp/claude-code-session.jsonl server: node dist/index.js ``` Закрепите любую нужную версию. Самая новая доступна на [странице релизов](https://github.com/kerlenton/mcpsnoop/releases). Все входные и выходные данные описаны в разделе [The GitHub Action](#the-github-action) ниже, а все сигналы, по которым может завершиться сбоем проверка, — в [docs/CI.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md). ## OpenTelemetry Ревизия MCP 2026-07-28 объявляет устаревшим протокольный Logging и рекомендует реализациям переходить на `stderr` при stdio или на OpenTelemetry для структурированной наблюдаемости. mcpsnoop поддерживает оба варианта, не затрагивая клиент или сервер. Строки `stderr` stdio-сервера отображаются в потоке рядом с его кадрами, а каждый запрос становится спаном, следующим [семантическим конвенциям OpenTelemetry для MCP](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/model/mcp). ```bash mcpsnoop export -T otlp -o trace.json # spans from a capture mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js # spans as calls complete ``` Вызов инструмента приходит в виде спана с именем `tools/call search`, несущего `mcp.method.name`, `gen_ai.tool.name` и `error.type`, поэтому он попадает в дашборд, созданный для MCP, а не для mcpsnoop. Живые метрики инструментов для Prometheus — на расстоянии одного флага. Оба описаны в [docs/OPENTELEMETRY.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/OPENTELEMETRY.md). ## Быстрый старт Увидьте это сразу, без какой-либо настройки. ```bash mcpsnoop demo ``` Чтобы использовать его по-настоящему, оберните ваш сервер в MCP-конфигурацию вашего клиента. ```json { "mcpServers": { "my-server": { "command": "mcpsnoop", "args": ["--", "node", "build/index.js"] } } } ``` Всё, что идёт после `--`, — это команда, которая обычно запускает ваш сервер. Подставьте ту, которую вы уже используете, например `python server.py`, `npx -y @scope/server` или скомпилированный бинарник. В Claude Desktop вам не нужно вносить это изменение вручную. ```bash mcpsnoop wrap my-server # route my-server through mcpsnoop mcpsnoop unwrap my-server # put it back ``` `wrap` находит `claude_desktop_config.json`, при первом запуске копирует его в `claude_desktop_config.json.mcpsnoop.bak` и перезаписывает только запись этого одного сервера, поэтому ваше форматирование и все остальные серверы остаются нетронутыми. Внутри перезаписанной записи ключи возвращаются в алфавитном порядке. `unwrap` восстанавливает файл и удаляет резервную копию, как только ни один сервер больше не обёрнут. После любого из этих действий перезапустите Claude Desktop, так как MCP-серверы запускаются один раз при старте. Затем используйте свой клиент как обычно и откройте UI. ```bash mcpsnoop ``` Никаких флагов, никаких путей к сокетам, никакого порядка запуска, который нужно запоминать. Shim и UI находят друг друга сами, а UI подгружает прошлые сессии с диска. Для сервера с потоковой передачей по HTTP запускайте mcpsnoop как обратный прокси. ```bash mcpsnoop http --target http://localhost:3000/mcp --listen :7000 ``` HTTP-статус каждого ответа отображается в потоке, поэтому ответ, не содержащий собственного сообщения JSON-RPC, всё равно остаётся видимым кадром, а не пустотой. Это охватывает запрос 401, 403 при отклонённом Origin, 202, подтверждающий уведомление, и 502, когда целевой сервер вообще недоступен. Заголовок `WWW-Authenticate` ответа 401 сохраняется дословно и показывается в инспекторе, поскольку он указывает схему аутентификации и метаданные ресурса, к которым следует обратиться далее. Фильтруйте по статусу с помощью `status:401` в TUI или по любой ошибке с помощью `status:err`. Код 4xx или 5xx считается ошибкой, поэтому запуск `mcpsnoop check` по умолчанию завершается неудачей на нём, а вызов, на который он ответил, читается как неудавшийся, а не как всё ещё ожидающий. Нет собственного сервера? [Попробуйте по-настоящему](https://github.com/kerlenton/mcpsnoop/blob/main/docs/TRY_IT.md) на опубликованном тестовом сервере, управляемом вашим собственным клиентом. Чтобы просмотреть сессию после того, как она произошла, см. [просмотр прошлых сессий из логов](https://github.com/kerlenton/mcpsnoop/blob/main/docs/POST_MORTEM.md). ## Установка ### npm Инструментарий Go не требуется. Большинство серверов MCP написаны на Node или Python, поэтому это самый короткий путь. ```bash npx mcpsnoop -- node build/index.js ``` Пакет npm не содержит собственного кода. Шесть платформенных пакетов содержат по одной сборке, и npm устанавливает только тот, который соответствует вашей машине, поэтому во время установки ничего не нужно скачивать и ничего не нужно разблокировать в прокси. Чтобы сохранить его, а не загружать при каждом запуске, выполните `npm i -g mcpsnoop`. ### Homebrew ```bash brew install mcpsnoop ``` ### Go ```bash go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest ``` Готовые бинарные файлы для каждой платформы доступны на странице [Releases](https://github.com/kerlenton/mcpsnoop/releases). mcpsnoop поставляется с автодополнением для bash, zsh, fish и PowerShell. Запустите `mcpsnoop completion <shell> --help`, чтобы узнать шаги настройки, которые охватывают включение автодополнения и путь установки для вашей ОС. ## Команды | Команда | Что она делает | |---|---| | `mcpsnoop -- <server>` | оборачивает stdio-сервер как прозрачный шим | | `mcpsnoop` | открывает живой TUI | | `mcpsnoop --metrics-listen <addr>` | запускает headless-хаб и предоставляет живые метрики Prometheus | | `mcpsnoop http --target <url>` | проксирует streamable-HTTP сервер | | `mcpsnoop export` | рендерит сессию в json, html, text, har или otlp | | `mcpsnoop check` | завершает CI с ошибкой при ошибках, недопустимых кадрах, предупреждениях, таких как результат инструмента, нарушающий собственную outputSchema, несоответствия маршрутизации, зависшие вызовы, поздние результаты, вызовы, которые могли выполниться дважды, дрейф инструментов, аннотации, которые ослабли или ничего не говорят, или превышение бюджета задержки | | `mcpsnoop baseline` | просматривает, принимает или сбрасывает доверенные определения инструментов | | `mcpsnoop diff` | сравнивает инструменты и вызовы между двумя записанными сессиями | | `mcpsnoop open` | открывает сохранённую сессию в TUI | | `mcpsnoop mock <session>` | воспроизводит записанную сессию как stdio MCP-сервер | | `mcpsnoop replay <session> -- <server>` | управляет сервером, через stdio или Streamable HTTP, клиентской стороной записанной сессии и сравнивает результат с записью | | `mcpsnoop inventory` | перечисляет каждый сервер, который запускался через mcpsnoop на этой машине | | `mcpsnoop stats` | сводит каждый сохранённый захват в одну строку на сервер и инструмент | | `mcpsnoop clients` | показывает, что каждый MCP-клиент фактически делал в сети, по имени и версии | | `mcpsnoop prune` | удаляет сохранённые журналы сессий старше заданного порога | | `mcpsnoop wrap <server>` | направляет один из серверов Claude Desktop через mcpsnoop | | `mcpsnoop unwrap <server>` | возвращает запись этого сервера в исходное состояние | | `mcpsnoop remote <user@host>` | выводит команду SSH-туннеля | | `mcpsnoop demo` | проигрывает сценарий сессии | Запустите `mcpsnoop help` для полного списка или `mcpsnoop help <command>` для флагов одной команды. ## Как это сравнивается Каждый из этих инструментов отвечает на другой вопрос, и место, где находится инструмент, определяет, на какие вопросы он может ответить. | Инструмент | Где он находится | Для чего он нужен | |---|---|---| | [MCP Inspector](https://github.com/modelcontextprotocol/inspector) | собственный клиент, подключённый к вашему серверу | ручное тестирование сервера в браузере или из скриптуемого CLI | | [Snyk Agent Scan](https://github.com/snyk/agent-scan) | собственный клиент, запускающий или подключающийся к серверам в ваших конфигурациях для чтения их инструментов | сканирование агентов, MCP-серверов и навыков на вашей машине на предмет prompt injection и уязвимостей | | [MCP Observatory](https://github.com/KryptosAI/mcp-observatory) | собственный клиент, запускающий ваш сервер для тестирования, записи и проверки | тестирование безопасности и регрессий в CI, с симуляцией атак, дрейфом схем и записью, воспроизведением и проверкой | | [mcprec](https://github.com/erphq/mcprec) | в сети, между клиентом и сервером | однократная запись сессии и её воспроизведение как тестовой фикстуры без сети | | mcpsnoop | в сети, между клиентом и сервером | наблюдение за тем, что говорят ваш реальный клиент и сервер, воспроизведение сессии реального клиента против каждой сборки, завершение CI с ошибкой на этом и экспорт в OpenTelemetry | Инструмент, который является собственным клиентом, видит вызовы, которые делает он сам, а не те, которые делает ваш клиент, поэтому он не может показать вызов, который ваша модель не сделала или сделала с неправильными аргументами. Сканер читает определение до того, как вы ему доверитесь. mcpsnoop наблюдает за тем, что происходит после того, как вы доверились, включая то, меняется ли определение позже. ## Как это работает <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg"> <img alt="mcpsnoop находится в канале между вашим AI-клиентом и вашими MCP-серверами, копируя каждый кадр JSON-RPC в живой терминальный UI" src="https://raw.githubusercontent.com/kerlenton/mcpsnoop/HEAD/assets/architecture-light.svg" width="760"> </picture> </p> mcpsnoop — это две роли в одном бинарнике. `mcpsnoop -- <server>` — это прозрачный shim, который запускает ваш клиент, передавая байты дословно и одновременно отправляя копию каждого кадра в хаб. `mcpsnoop` без аргументов — это тот самый хаб и его живой TUI. Они связываются через общеизвестный сокет и логи на диске, поэтому ни одному из них не нужно запускаться первым. Поскольку он находится в самом канале передачи, а не сбоку, как Inspector, он видит ровно то, что ваш реальный клиент и сервер говорят друг другу, независимо от того, на чём написан сервер. Что ограничивает его память и диск, описано в [docs/HOW_IT_WORKS.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/HOW_IT_WORKS.md). ## GitHub Action Всё ниже — это то, что action делает за вас. Он устанавливает mcpsnoop, проверяет захват, заносит находки во вкладку Security и проваливает задание по тем критериям, которые вы задали. ```yaml permissions: security-events: write contents: read steps: - uses: kerlenton/[email protected] with: session: artifacts/session.jsonl ``` Закрепите релиз, любой, какой захотите. Самый новый находится на [странице релизов](https://github.com/kerlenton/mcpsnoop/releases). Плавающего `v1` намеренно нет. Закреплённый релиз — это также бинарник, который устанавливает действие, поэтому они никогда не могут разойтись, и нет версии по умолчанию, которая устареет. | Вход | | |---|---| | `session` | захват `.jsonl` для проверки или каталог с ними, относительно корня репозитория. Укажите это или `replay` | | `replay` | закоммиченная запись для воспроизведения против `server` или `target`, чей захват затем проверяется и тоже проваливает задание при регрессии | | `server` | команда, запускающая тестируемый сервер, в кавычках, как в командной строке. Обязательна с `replay` для stdio-сервера. С `target` сначала запускает HTTP-сервер и может быть опущена, если он уже запущен | | `target` | конечная точка Streamable HTTP для воспроизведения, например `http://localhost:3000/mcp`. Учётные данные передаются в `replay-args` как `--header`, и в журнале шага их значение отображается скрытым | | `replay-args` | любые другие флаги `replay`, например `--read-only`. `--out` отклоняется, так как действие решает, куда идёт захват | | `fail-on` | как `--fail-on`, по умолчанию совпадает с тем, что использует CLI по умолчанию | | `args` | любые другие флаги `check`, в кавычках, как в командной строке. `--format` отклоняется, так как действие читает отчёт | | `upload-sarif` | отправить отчёт в сканирование кода. `true` | | `category` | пространство имён сканирования кода. `mcpsnoop`. Меняйте его для каждой ветви матрицы, иначе ветви перезаписывают друг друга | | `fail-on-findings` | провалить задание при находке. `true`. Установите `false`, чтобы зарегистрировать оповещения и позволить обязательной проверке сканирования кода принять решение | | `version` | какой mcpsnoop установить. По умолчанию — закреплённый вами релиз | | `install` | `false`, когда mcpsnoop уже в PATH, что является способом входа на платформе, для которой не собирается ни один релиз | Выходы — `outcome`, `sarif`, `exit-code` и `capture`, путь проверенного захвата, который при `replay` является тем, что записал replay, и его стоит сохранить как артефакт. `outcome` — это `passed`, `findings` или `error`, и третий стоит обрабатывать отдельно. Он означает, что ничего не было проверено, что не то же самое, что ничего не найдено. **Запуск, который не смог проверить, проваливает задание, что бы ни говорил `fail-on-findings`**, потому что конвейер, который становится зелёным, ничего не проверив, хуже, чем тот, который падает. Заданию нужен `security-events: write`, иначе загрузка вернёт 403. Установите `upload-sarif: false` в репозитории без сканирования кода. Запуск той же проверки без действия, сигналы, на которых она может провалиться, и коды выхода — в [docs/CI.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md). ## Документация | Страница | Что в ней | |---|---| | [Проверка сессий в CI](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md) | воспроизведение записи против каждой сборки, каждый сигнал, на котором может провалиться `check`, коды выхода, утверждения, отчёты JUnit и SARIF, сравнение двух сессий и настройка без действия | | [OpenTelemetry и Prometheus](https://github.com/kerlenton/mcpsnoop/blob/main/docs/OPENTELEMETRY.md) | спаны и что они несут, их потоковая передача в коллектор и метрики инструментов в реальном времени | | [Использование mcpsnoop](https://github.com/kerlenton/mcpsnoop/blob/main/docs/USING.md) | клавиши, фильтрация, форматы экспорта, replay, что сервер запросил у вашего пользователя, стоимость в контексте, статистика по захватам, что на самом деле отправляет каждый клиент, инвентарь серверов, удалённые машины и файл конфигурации | | [Редактирование](https://github.com/kerlenton/mcpsnoop/blob/main/docs/REDACTION.md) | очистка секретов во время захвата или из уже имеющегося захвата | | [Как это работает](https://github.com/kerlenton/mcpsnoop/blob/main/docs/HOW_IT_WORKS.md) | ограничения памяти, лимит истории и обрезка старых журналов | | [Попробуйте по-настоящему](https://github.com/kerlenton/mcpsnoop/blob/main/docs/TRY_IT.md) | опубликованный тестовый сервер, управляемый вашим собственным клиентом | | [Обзор прошлых сессий](https://github.com/kerlenton/mcpsnoop/blob/main/docs/POST_MORTEM.md) | где хранятся журналы сессий и как открыть один после факта | | [Формат захвата](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CAPTURE_FORMAT.md) | что содержит каждая строка журнала сессии и что в нём никогда не изменится, с JSON Schema для инструментов, читающих захваты | ## Безопасность mcpsnoop запускает команду сервера, которую вы оборачиваете, поэтому оборачивайте только серверы, которым доверяете, и запускайте недоверенные в контейнере. Он никогда не выполняет ничего, чего вы не поместили в конфигурацию вашего клиента. Для удалённых рабочих процессов используйте SSH-туннелирование или передачу файлов по SSH, чтобы аутентификация транспорта, шифрование, проверка хоста, ротация ключей и политика аудита оставались в вашей существующей конфигурации SSH. ### Что захват может сделать с вашим терминалом Захват — это данные, которые выбрала другая сторона. Кадры и строки stderr могут содержать управляющие последовательности терминала, а терминал выполняет всё, что ему передают, — от искажённого отображения до записи в системный буфер обмена через OSC 52. mcpsnoop сохраняет только цветовые последовательности, которые генерирует сам, и отбрасывает все остальные escape-последовательности до того, как кадр достигнет вашего терминала. Ячейки таблицы экранируют управляющие символы, чтобы вы видели, что они там были, инспектор выводит их полностью, а копирование в буфер обмена содержит экранированную форму, так что ничего не скрыто от вас и ничего не выполняется. ### Что содержит захват Захваченные кадры могут включать промпты, аргументы инструментов, учётные данные и результаты инструментов. [docs/REDACTION.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/REDACTION.md) описывает их очистку — как во время захвата, так и после. Чтобы сообщить об уязвимости, см. [SECURITY.md](https://github.com/kerlenton/mcpsnoop/blob/main/SECURITY.md). ## Участие в разработке Issues и pull requests приветствуются. Подробности см. в [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/main/CONTRIBUTING.md). ## Лицензия [MIT](https://github.com/kerlenton/mcpsnoop/blob/main/LICENSE)
