Metadata-Version: 2.4
Name: mcp-checkup
Version: 0.0.1
Summary: 🩺 A health check for your MCP setup — measure the context tax and hygiene of your MCP servers
Project-URL: Homepage, https://github.com/mohitgurnani1/mcp-checkup
Project-URL: Repository, https://github.com/mohitgurnani1/mcp-checkup
Project-URL: Issues, https://github.com/mohitgurnani1/mcp-checkup/issues
Author: Mohit Gurnani
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: audit,cli,llm,mcp,model-context-protocol,tokens
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 🩺 mcp-checkup

**A health check for your MCP setup.**

One command that tells you what your MCP servers *cost* you — in context-window
tokens and dollars — and whether they follow basic security hygiene.

[![CI][badge-ci]][ci] [![PyPI][badge-pypi]][pypi] [![Python][badge-py]][pypi]
[![License][badge-license]][license] [![Ruff][badge-ruff]][ruff]

---

## The problem

Every MCP server you connect injects its full tool schemas into your model's
context window — on **every single request** — before you type a word.

- GitHub's official MCP server alone consumes **~17,600 tokens per request** in
  tool definitions ([autopsy][gh-mcp-cost]).
- Teams have burned **72% of a 200k context window** on tool definitions before
  doing any actual work ([MCP spec issue #2808][spec-2808]).
- A security audit of publicly exposed MCP servers found **119 out of 119
  sampled allowed unauthenticated access** to internal tool listings.

You are paying a *context tax* on every request, and you probably have no idea
how big it is. `mcp-checkup` measures it.

## What it looks like

> ⚠️ **Target UX — under active development.** The output below is the design
> we are building toward. Today the CLI installs and prints the roadmap.

```text
$ uvx mcp-checkup

  🩺 MCP Checkup — 4 servers, 38 tools

  WEIGHT                                    HYGIENE
  ────────────────────────────────────     ─────────────────────────────────
  github       17,612 tok   $0.053/req     ⚠ 2 tools reachable without auth
  slack         4,105 tok   $0.012/req     ✓ ok
  filesystem    2,890 tok   $0.009/req     ⚠ unrestricted root path
  custom-api    9,441 tok   $0.028/req     ⚠ 3 schemas 8× over minimal size

  Context tax: 34,048 tokens — 17% of a 200k window, before your first message.

  Run `mcp-checkup --fix` to emit compressed schemas.
  Run `mcp-checkup --fail-over 20000` in CI to stop the bloat from coming back.
```

## Quickstart

```bash
uvx mcp-checkup          # or: pip install mcp-checkup
```

Point it at your client config (`.mcp.json`, Claude Desktop, Cursor, …) or a
running server. That's the whole interface — one command, one report.

## Roadmap

- [ ] **Weight** — per-tool token count of every server's schemas (tiktoken +
      Anthropic token counting)
- [ ] **Weight** — $ cost per session per model (GPT, Claude, Gemini pricing tables)
- [ ] **Hygiene** — missing auth, exposed tool listings
- [ ] **Hygiene** — bloated schemas (vs. minimal equivalent), suspicious /
      injection-prone tool descriptions
- [ ] `--fix` — emit compressed schemas that preserve call structure
- [ ] CI mode — `--fail-over <tokens>` budget gate for your pipeline
- [ ] Client config auto-discovery (Claude Desktop / Claude Code / Cursor / Windsurf)

## Status

Early days — the measurement engine is being built in the open. If the context
tax bothers you too: ⭐ star the repo to follow along, open an issue with your
worst MCP token bill, or see [CONTRIBUTING.md](CONTRIBUTING.md) to help build it.

## License

[Apache-2.0](LICENSE)

[badge-ci]: https://github.com/mohitgurnani1/mcp-checkup/actions/workflows/ci.yaml/badge.svg
[ci]: https://github.com/mohitgurnani1/mcp-checkup/actions/workflows/ci.yaml
[badge-pypi]: https://img.shields.io/pypi/v/mcp-checkup
[pypi]: https://pypi.org/project/mcp-checkup/
[badge-py]: https://img.shields.io/pypi/pyversions/mcp-checkup
[badge-license]: https://img.shields.io/badge/license-Apache--2.0-blue
[license]: LICENSE
[badge-ruff]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[ruff]: https://github.com/astral-sh/ruff
[gh-mcp-cost]: https://getunblocked.com/blog/github-mcp-token-cost/
[spec-2808]: https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2808
