Metadata-Version: 2.4
Name: mcp-snoop
Version: 0.1.0
Summary: Transparent stdio interceptor for MCP JSON-RPC traffic. Like strace, but for MCP.
Project-URL: Homepage, https://github.com/0-co/mcp-snoop
Project-URL: Repository, https://github.com/0-co/mcp-snoop
Project-URL: Issues, https://github.com/0-co/mcp-snoop/issues
License: MIT
License-File: LICENSE
Keywords: debugging,mcp,model-context-protocol,stdio,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# mcp-snoop

**Transparent stdio interceptor for MCP JSON-RPC traffic.**

Like `strace`, but for the Model Context Protocol. Wrap any MCP server and see every message in real time — tool calls, responses, errors. Zero dependencies.

```
$ mcp-snoop -- python3 my_server.py
mcp-snoop intercepting: python3 my_server.py
[03:14:22.847] →SERVER #1 initialize claude-desktop v1.0
[03:14:22.912] ←CLIENT #1 → server: my-server v0.1.0
[03:14:22.913] →SERVER notifications/initialized
[03:14:22.914] →SERVER #2 list tools
[03:14:22.916] ←CLIENT #2 → 8 tools
[03:14:23.201] →SERVER #3 call search_files(path="/tmp", pattern="*.py")
[03:14:23.847] ←CLIENT #3 → text: "['server.py', 'handler.py']"

mcp-snoop: 7 messages intercepted
```

## Install

```bash
pip install mcp-snoop
```

Or run without installing:

```bash
uvx mcp-snoop -- python3 my_server.py
```

## Usage

```bash
# Basic — logs all messages to stderr
mcp-snoop -- python3 my_server.py

# Verbose — print full JSON for each message
mcp-snoop --verbose -- node server.js

# Save trace to file
mcp-snoop --output trace.log -- uvx my-mcp-server

# No color (for CI/log files)
mcp-snoop --no-color -- python3 server.py
```

## What you see

Each log line shows:
- **timestamp** — `HH:MM:SS.mmm` UTC
- **direction** — `→SERVER` (client→server) or `←CLIENT` (server→client)
- **message ID** — `#1`, `#2`, etc. (pairs requests with responses)
- **summary** — parsed tool name, arguments, result preview

With `--verbose`, the full JSON follows.

## Why

You're building an MCP server. Your agent keeps calling the wrong tool. Something's returning garbage. The MCP Inspector requires a browser. You want to script against the logs.

`mcp-snoop` gives you the raw protocol traffic, right in your terminal.

## Use in Claude Desktop / cline / any MCP client

Replace your server command with `mcp-snoop -- <your command>`:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcp-snoop",
      "args": ["--output", "/tmp/trace.log", "--", "python3", "my_server.py"]
    }
  }
}
```

All traffic between the client and your server is now logged to `/tmp/trace.log`.

## Relationship to other tools

| Tool | What it does |
|------|-------------|
| [agent-friend](https://github.com/0-co/agent-friend) | Grades MCP schema quality (A+ to F) |
| [mcp-patch](https://github.com/0-co/mcp-patch) | AST security scanner for MCP servers |
| [mcp-pytest](https://github.com/0-co/mcp-test) | pytest integration for testing MCP servers |
| **mcp-snoop** | Stdio interceptor — debug live protocol traffic |

## License

MIT
