Metadata-Version: 2.5
Name: mcpgawk
Version: 0.1.93
Summary: Catches an MCP server that changed after you approved it, and holds the call before your agent runs it. Your inventory stays on your machine.
Project-URL: Homepage, https://mcp.gawk.dev
Project-URL: Documentation, https://mcp.gawk.dev/docs
Project-URL: Repository, https://github.com/gawk-dev/mcpgawk
Project-URL: Issues, https://github.com/gawk-dev/mcpgawk/issues
Project-URL: Changelog, https://github.com/gawk-dev/mcpgawk/releases
Author: Neelagiri
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agentic-ai,agents,ai-security,cli,llm,local-first,mcp,mcp-gateway,model-context-protocol,post-approval-drift,prompt-injection,rug-pull,security,supply-chain-security,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: httpx2>=2
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.2
Requires-Dist: pyyaml>=6
Requires-Dist: tiktoken>=0.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: gateway
Requires-Dist: starlette>=0.40; extra == 'gateway'
Requires-Dist: uvicorn>=0.30; extra == 'gateway'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/wordmark-dark.png">
    <img alt="mcpgawk by nativerse" src="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/wordmark-light.png" width="320">
  </picture>
</p>
<p align="center"><em>One gateway in the path. On your machine.</em></p>
<p align="center"><a href="https://www.producthunt.com/products/mcpgawk?launch=mcpgawk"><img alt="mcpgawk on Product Hunt" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1259498&theme=light" width="250" height="54"></a><br>Featured on Product Hunt.</p>

# mcpgawk
<!-- mcp-name: io.github.gawk-dev/mcpgawk -->

[![PyPI](https://img.shields.io/pypi/v/mcpgawk.svg)](https://pypi.org/project/mcpgawk/)
[![Python](https://img.shields.io/pypi/pyversions/mcpgawk.svg)](https://pypi.org/project/mcpgawk/)
[![License](https://img.shields.io/badge/license-Apache--2.0-C8401F.svg)](https://github.com/gawk-dev/mcpgawk/blob/main/LICENSE)
[![CI](https://github.com/gawk-dev/mcpgawk/actions/workflows/ci.yml/badge.svg)](https://github.com/gawk-dev/mcpgawk/actions/workflows/ci.yml)
[![Open VSX](https://img.shields.io/open-vsx/v/gawk-dev/mcpgawk?label=VS%20Code%20%2F%20Cursor)](https://open-vsx.org/extension/gawk-dev/mcpgawk)
[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Action-C8401F?logo=github)](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)
[![Local-first](https://img.shields.io/badge/inventory-stays%20local-brightgreen.svg)](#guarantees)

Your agents call [Model Context Protocol](https://modelcontextprotocol.io) servers that can
change what their tools do *after* you approved them, and the agent will call the new one without
noticing. mcpgawk reads every server your agents can reach, checks every call against a baseline
you approved, and blocks the ones that changed. It runs on your machine: your servers, approvals and call log stay there, and nothing about them is
sent unless you ask for it (`mcpgawk push`, `--supply-chain`).

The same engine powers **mcpgawk Platform**: `mcpgawk enforce` puts one endpoint in front of the
whole fleet with a key per caller, policy on every call and a hash-chained audit log, and
`mcpgawk monitor` watches the servers you approved around the clock and tells you when one drifts.
This free layer is the seeing and the blocking underneath it. mcpgawk Platform is one subscription
per person for up to 3 machines: start a free 7-day trial at https://mcp.gawk.dev/trial.html?utm_source=github&utm_medium=readme
(no card) or subscribe at https://mcp.gawk.dev/subscribe. Then `mcpgawk login <key>` on this same
install fetches the paid engine and turns those on — one more command, nothing else to set up.

<p align="center">
  <a href="https://mcp.gawk.dev/gh#watch"><img src="https://mcp.gawk.dev/assets/video/mcpgawk-launch-poster.jpg" width="720"
       alt="mcpgawk in 64 seconds: a tool you approved changes in an update, and mcpgawk refuses the call until you decide. Watch the video."></a>
</p>
<p align="center"><sub><b>Watch: mcpgawk in 64 seconds.</b> A tool you approved changes in an update; mcpgawk refuses the call until you decide.</sub></p>

<p align="center">
  <img src="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/demo.gif"
       alt="mcpgawk demo: a server is approved, changes afterwards, and the guard blocks the tool that appeared">
</p>
<p align="center"><sub><code>mcpgawk demo</code> — its own output, in a sandbox that touches nothing of yours.
Recorded on 0.1.54.</sub></p>

## Why

A server you approved can change what its tools do afterwards. Nothing in MCP tells your agent that
happened — it just calls the new tool. That is the rug-pull, and it is the case mcpgawk is built for.

Two things follow from being able to see a server properly. You find out what each one can reach
before you trust it, and you find out what it costs: every tool is loaded into your context on every
request, used or not.

## How it's different

- **It blocks, it does not only report.** A scanner tells you afterwards. `mcpgawk guard` installs one
  pre-execution hook and a tool that appeared after you approved the server does not run.
- **It runs the server, not just reads it.** `mcpgawk verify` drives tools in a sandbox and reports
  what they actually did — exfiltration, SSRF, poisoning — reproduced before it is reported.
- **Your inventory stays on your machine.** Cloud scanners send your inventory to a server and gate the verdict there.
  Every decision here is made on your machine, and the free tools need no account.
- **It says what it did not check.** Skipped tools are named as skipped, never counted as clean.

## Features

- 🛑 **Block a changed tool before it runs** — running `mcpgawk` puts one pre-execution hook in the
  loop of each agent on your machine that has a hook point (`mcpgawk guard install` does Claude Code alone). The decision is local, with nothing to sign in to. Works on **6 of
  the 21 supported clients**; the rest have no hook point and are named, not glossed over.
- 🧪 **Run it, don't just read it** — `mcpgawk verify` drives tools in a sandbox and reports what they
  did: exfiltration, SSRF, tool poisoning, secret leaks. The sandbox is a proxy by default, so it
  needs no Docker; Docker adds full container isolation when you have it. Safe mode drives only
  provably read-only tools, and every tool it skips is named as skipped.
- 🧑‍⚖️ **mcpgawk refuses an approval when it can see an agent running it** — `mcpgawk decide` opens a
  local screen for what changed. The buttons live on the tokened link printed in your terminal.
- 🖥️ **One local panel** — `mcpgawk panel`: every server, every decision, every piece of evidence.
- 📜 **The changelog no vendor publishes** — `mcpgawk changes` shows every change to a server's tool
  surface between the snapshots you have recorded: tools added or removed, input schemas widened,
  descriptions and annotations rewritten. It reads your local history, so it works for a server you
  approved weeks ago — the one thing a fresh scan can never tell you.
- 🔌 **Any transport** — stdio, streamable-HTTP, SSE, and OAuth remotes (via the `mcp-remote` bridge).
- 💸 **Token cost index** — exactly what each tool adds to your context at connect, plus the 3 heaviest tools.
- 🧾 **Capability facts** — write / exfil-capable / declared annotations, straight from the schema, plus a
  trust-surface summary (% write, % exfil-capable, destructive-declared count) and an annotation-completeness
  score.
- 📌 **Integrity pin + drift** — catch a server that silently rewrites its tools. Every scan is recorded locally; `--no-track` skips it.
- 🚩 **Bounded signals** — injection-shaped descriptions, cross-server shadowing, under-declaring Server Cards — pointers for a human, never verdicts.
- 🔒 **Your inventory stays on your machine** — the measurement layers import no network library. Enforced by a test.
  Two checks are opt-in and make an explicit exception (see [Guarantees](#guarantees)): `--supply-chain` and
  `--oauth-scopes`.

## Get it — three ways

[![Install mcpgawk from PyPI, the VS Code Marketplace or Open VSX (13-second film)](https://mcp.gawk.dev/assets/video/mcpgawk-registries-poster.jpg)](https://youtu.be/Gu-6oriEBio)

**CLI** (any terminal):
```bash
uv tool install --force mcpgawk      # or: pipx install --force mcpgawk
mcpgawk                              # finds every agent config on the machine itself
```

Run it as an MCP server: `mcpgawk mcp` (stdio), or `uvx mcpgawk mcp`.

**Editor** (VS Code / Cursor): install **mcpgawk** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gawk-dev.mcpgawk) or [Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk). It is a sidebar panel: every MCP server configured across your AI tools, grouped by the tool it lives in, with what each one can reach and which need attention. The extension drives this engine as a subprocess — it is built and released separately, so its source is not in this repository.

**CI** (GitHub Action): gate every PR on token budget, flagged signals and, with a committed baseline, a server that changed since you approved it ([Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)):
```yaml
- uses: gawk-dev/mcpgawk@v1
  with: { config: mcp.json, max-tokens: 8000, fail-on-flagged: true }
```

## When to run it

- **Once, then leave it on** — `mcpgawk`. It adds the hook to each of the six agents with a hook point
  that it finds on your machine (Claude Code, Codex, Cursor, Gemini CLI, Kimi, Windsurf), writing their
  hook configs. After that a tool that changed or appeared on a server you already approved is refused
  before it runs.
- **Before you add a server** — see what it costs and what it can do, before you trust it.
- **When your agent feels slow or picks the wrong tool** — it's often MCP bloat (too many / too-heavy tools).
- **On every PR** — the CI gate catches creeping token cost and flagged signals, and, given a committed baseline, a server that changed since you approved it.
- **If you *publish* an MCP server** — see what it costs your users and how it reads to a client, and fix it (usually one line per tool). Lean + well-annotated is a differentiator.

## Use

```bash
mcpgawk                                  # first run: every agent config on this machine
mcpgawk demo                             # the whole arc in a sandbox — approve, drift, block
mcpgawk guard install                    # the hook in Claude Code only (bare `mcpgawk` does all six)
mcpgawk guard status                     # is protection actually on?
mcpgawk decide                           # what changed, and approve it as a human
mcpgawk panel                            # the local page: servers, decisions, evidence
mcpgawk verify mcp.json                  # run the servers and watch what they do
mcpgawk changes                          # what changed on your servers since you approved them
mcpgawk login <key>                      # licence? one command fetches the paid engine (enforce, monitor)
```

Scanning on its own, if that is all you want:

```bash
mcpgawk scan mcp.json                                              # a whole config
mcpgawk scan --stdio "npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /tmp"
mcpgawk scan --http https://host/mcp --header "Authorization: Bearer $TOKEN"
mcpgawk scan --sse  https://host/sse
mcpgawk scan mcp.json                                             # recorded locally: the next scan reports what changed
mcpgawk scan mcp.json --no-track                                  # measure without recording
mcpgawk scan mcp.json --json                                      # machine-readable labels
mcpgawk scan mcp.json --verbose                                   # full per-tool table, not just flagged tools
mcpgawk scan mcp.json --supply-chain                              # opt-in: npm/PyPI deprecation check (network)
mcpgawk scan mcp.json --oauth-scopes                              # opt-in: decode a supplied Bearer JWT's scope
```

Keep tokens out of the config file. Under `mcpgawk wrap`, an `env` value written as `keychain:<service>`
(or `keychain:<service>@<account>`) is read from your macOS Keychain when the server starts and placed
in the server's environment only. The config holds a reference, the agent sees a reference, mcpgawk
stores nothing. A reference that cannot be read refuses to start the server and names the reference,
never a value.

```json
"github": { "command": "mcpgawk", "args": ["wrap", "--", "npx", "-y", "@modelcontextprotocol/server-github"],
            "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "keychain:gh-work" } }
```

## What it reports

- **Cost index** — tokens each tool adds at connect (named tokenizer; a comparable index, not an
  absolute Claude count), plus the 3 heaviest tools.
- **Trust surface** — capability facts (write/mutating, exfil-capable, declared annotations) rolled up
  into % write, % exfil-capable, and a destructive-declared count.
- **Annotation completeness** — a transparent composite (annotated ÷ total tools declaring read/write
  intent), not a risk score.
- **Coverage** — tools, prompts, and resources counted (`--verbose` for the full per-tool table).
- **Integrity pin** — a hash that changes if the server silently rewrites its tools. Scans are
  recorded locally by default, which turns it into rug-pull detection over time (`--no-track` skips it).
- **Bounded signals** — precise, low-false-positive pointers *for a human to review*, never verdicts:
  injection-shaped descriptions (tools **and** prompts), cross-server name shadowing, and public
  Server Cards that under-declare what the server actually exposes.
- **Supply-chain** (opt-in, `--supply-chain`) — checks the launched package against the public npm/PyPI
  registry for deprecation/yank status.
- **OAuth scopes** (opt-in, `--oauth-scopes`) — locally decodes a supplied Bearer JWT's `scope` claim.

## Guarantees

- **Your servers, approvals and call log stay on your machine.** Nothing about them is sent unless
  you ask for it (`mcpgawk push`, `--supply-chain`). Every network connection mcpgawk makes:
  - the protocol client talking to the servers you point it at;
  - one anonymous request to PyPI about once a day asking whether a newer mcpgawk exists (it says
    nothing about your servers; `MCPGAWK_NO_UPDATE_CHECK=1` turns it off);
  - `--supply-chain`, only when you pass it: sends the launched package's name (and pinned version,
    if any) — never your tool inventory — to the public npm registry or PyPI JSON API;
  - `mcpgawk install-node`, only when you run it: downloads Node from nodejs.org;
  - `mcpgawk login`, only when you run it: sends your key to mcp.gawk.dev, and a paid key is checked
    with Lemon Squeezy (at login, then about once a day). On a free install it then downloads the paid engine from a short-lived signed
    link that mcp.gawk.dev returns, and checks its sha256 before installing it;
  - OAuth sign-in, only when you ask for it: your browser and mcpgawk talk to that server's sign-in
    endpoints;
  - `mcpgawk push`, only when you run it: sends a scan report to your hosted fleet view;
  - `mcpgawk verify --webhook <url>`, only when you pass it: posts the verify report to that URL when
    there are findings or drift.

  The measurement layers import no network library — they *cannot* egress by construction
  (enforced by a test). Public Server Card discovery is fetched with no auth and no redirect-following.
  `--oauth-scopes` makes no network call at all; it locally decodes a Bearer JWT you already supplied.
- **Facts ≠ heuristics.** Exact capability facts and the token index never mix with the bounded
  heuristic signals — separate in code, separate in output.
- **Reproducible.** One command, identical numbers.
- **Tracks the protocol.** Built on the official `mcp` SDK, which negotiates the protocol version.

## Develop

```bash
uv run --extra dev --with mcp --with tiktoken --with httpx python -m pytest -q
```

## CI gate — GitHub Action

Scan your MCP servers on every pull request and fail the build if one gets too heavy or trips a signal.
Give it a committed copy of your approvals and it also fails when a server changed since that copy, or is not in it.
It runs entirely in your runner — your inventory stays there — and posts a per-server cost/flag table to the job summary.

```yaml
- uses: gawk-dev/mcpgawk@v1
  with:
    config: mcp.json        # local (stdio) servers named in it are started on the runner
                            # or: stdio / http / sse — a single server
    baseline: mcpgawk-baseline.json   # optional: a committed copy of your ~/.mcpgawk/history.json
    max-tokens: 8000        # fail if any server loads more than this at connect
    fail-on-flagged: true   # fail if any bounded signal fires
```

Without `baseline` there is nothing to compare against, so changes are not checked. The baseline file is
only read. It records your server names and who approved them, so commit it only where that is fine to share.

Available on the [GitHub Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate).

## Contributing

Issues and PRs welcome. Please read [CONTRIBUTING.md](https://github.com/gawk-dev/mcpgawk/blob/main/CONTRIBUTING.md) first, and see the design
boundaries in [THREAT-MODEL.md](https://github.com/gawk-dev/mcpgawk/blob/main/THREAT-MODEL.md). Security reports go through [SECURITY.md](https://github.com/gawk-dev/mcpgawk/blob/main/SECURITY.md)
(privately, not a public issue).

## License

**Apache-2.0** — see [LICENSE](https://github.com/gawk-dev/mcpgawk/blob/main/LICENSE). Part of the [**nativerse**](https://nativerse-ventures.com/) · [gawk.dev](https://gawk.dev/) family. Site and docs: [mcp.gawk.dev](https://mcp.gawk.dev/?utm_source=github&utm_medium=readme). The value is in the
repo, not a cloud.

## Use it from your agent (skill)

Let your coding agent run the checks itself — whenever it adds, upgrades or audits an MCP server:

```bash
# Claude Code: install the plugin (the skill, nothing else)
/plugin install mcpgawk --marketplace gawk-dev/mcpgawk

# Any other agent: copy the skill folder into its skills directory
mkdir -p ~/.claude/skills && cp -r plugin/skills/mcpgawk ~/.claude/skills/mcpgawk
```

The skill teaches the agent to measure a server BEFORE trusting it and relay every consent prompt to you verbatim.
