Install & downloads

Five surfaces. The CLI is the engine; everything else is a way of reaching it.

1 · The CLI — PyPI

The engine. Everything else on this page depends on it being installed.

uv tool install --force mcpgawk      # recommended: isolated, always on PATH
pipx install --force mcpgawk         # same idea, if you already use pipx
python3 -m pip install --user --upgrade mcpgawk   # anywhere Python 3.10+ is; fix PATH yourself

pypi.org/project/mcpgawk · Apache-2.0 · free forever, no account.

Which one? uv tool install if you have uv: it isolates the package and puts the binary somewhere already on your PATH, which is the single most common install problem. Plain pip install into a system Python is the most likely to end in command not found.

2 · VS Code — Marketplace

The fleet, in the sidebar. It shells out to the CLI on your machine and renders what comes back; it is a view, not a second engine.

code --install-extension gawk-dev.mcpgawk

Extension ID gawk-dev.mcpgawk. Requires the CLI above.

3 · VSCodium, Cursor, Windsurf and friends — Open VSX

The same extension, published to the registry those editors use instead of the Microsoft one.

codium --install-extension gawk-dev.mcpgawk

open-vsx.org/extension/gawk-dev/mcpgawk.

Open VSX download counts include registry mirroring and are not a usage number. We do not quote them as traction, and neither should you.

4 · CI — the GitHub Action

Gate a merge on what an MCP server actually is, in the pipeline rather than on a laptop.

- uses: gawk-dev/mcpgawk/action@main
  with:
    fail-on-flagged: true

Exit codes are the contract: 0 clean, 1 findings, 4 incomplete. Fail the build on 4 as well as 1 — a run that could not finish is not a pass.

5 · As an MCP server — so your agent can ask

Installing the CLI also installs mcpgawk-mcp, which exposes two read-only tools (scan_mcp_fleet, scan_mcp_server) so an agent can check this machine's scanner before trusting a server.

claude mcp add mcpgawk -- mcpgawk-mcp

The same server is reachable through the one binary as mcpgawk mcp, so a client that can only name a package can run it as uvx mcpgawk mcp.

It is read-only and refuses nothing by itself. Call-time refusal is the guard hook (Quickstart step 3), and it refuses to launch stdio servers unless the caller asks.

Check where your copy came from

From 0.1.73, every file on PyPI carries a signed record of where it was built: our public repository's release workflow, through PyPI trusted publishing. No API token can publish mcpgawk, so a stolen one cannot ship a fake release. You can check the record yourself:

uvx pypi-attestations verify pypi --repository https://github.com/gawk-dev/mcpgawk \
    pypi:mcpgawk-0.1.73-py3-none-any.whl

OK means the file PyPI serves was built by that repository. A file signed by any other repository fails, and so does any release before 0.1.73, which predates the signing. Swap in the version you installed (mcpgawk --version).

Keeping it current

mcpgawk --version
uv tool install --force mcpgawk     # or: pipx install --force mcpgawk

The extension and the CLI are released in lockstep on the same version number. A mismatch is worth reporting.