🔍 mcp-grade
Stop debugging dead MCP servers. One command grades any MCP server A–F on security, liveness, protocol, usability, and docs — then can probe it live and rank the whole ecosystem on a leaderboard.
The MCP ecosystem has 15,000+ servers — and roughly 1 in 6 has a verified problem: dead repos, deprecated packages, stale code, leaked secrets. mcp-grade is the fast, opinionated linter + Lighthouse you run before you wire a server into your agent.
✨ Why
- One command, instant grade. No config, no signup, <5 seconds.
- Security first. Catches hardcoded secrets, committed
.envfiles, andeval/exec— weighted so a leaky server can never score well. - Prove it actually runs.
--livelaunches the server and verifies the real MCP handshake. - Shareable report cards. Export a Markdown card + shields badge for your README or PRs.
- CI-native. A GitHub Action +
--fail-undermake it a quality gate that fails the build. - Ecosystem leaderboard. Rank popular servers and publish a public scoreboard.
📦 Install
pipx install mcp-grade # core CLI
pipx install "mcp-grade[live]" # + live protocol probing
pip install "mcp-grade[web]" # + the leaderboard web dashboard
🚀 Quickstart
mcp-grade ./path/to/server # grade a local repo
mcp-grade ./path/to/server --report --badge # + Markdown card + README badge
mcp-grade https://github.com/someone/server # clone & scan a remote repo
mcp-grade ./path/to/server --json report.json # machine-readable output
mcp-grade . --fail-under B # CI gate
🔬 Live protocol probing
Static analysis tells you a server looks right; --live proves it runs and answers. It launches the server over stdio and performs a real MCP handshake (initialize → list_tools):
pipx install "mcp-grade[live]"
mcp-grade ./path/to/server --live
# optionally control the launch command:
mcp-grade ./path/to/server --live --command "python server.py"
Live results (live_handshake, live_lists_tools) are folded into the Protocol score. It's off by default so the core scan stays fast and offline.
🏆 Leaderboard
Rank a set of servers (or the whole ecosystem) and publish a scoreboard:
mcp-grade-leaderboard ./serverA ./serverB --html leaderboard.html --json lb.json
mcp-grade-leaderboard --from-file leaderboard/repos.txt --md leaderboard.md
mcp-grade-leaderboard # no args → scan the curated list of popular servers
Serve it as a live dashboard (deploy to Fly.io / Render / Railway):
pip install "mcp-grade[web]"
MCP_GRADE_TARGETS=./examples/good_server,./examples/bad_server \
uvicorn mcp_grade.webapp:app --reload
# → http://127.0.0.1:8000 (HTML) and /api/leaderboard (JSON)
🤖 GitHub Action
Run mcp-grade automatically on every pull request — and fail the build if a server drops below your bar.
# .github/workflows/mcp-grade.yml
name: mcp-grade
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lipon101/mcp-grade@v1
id: scan
with:
fail-under: B
- name: Show grade
if: always()
run: echo "Grade ${{ steps.scan.outputs.grade }} (${{ steps.scan.outputs.score }}/100)"
Every repo that adds this Action becomes a dependent — visible under Insights → Dependents. New servers can start from mcp-server-template, which has this gate pre-wired.
🧪 What it checks
| Category | Weight | Examples |
|---|---|---|
| 🔒 Security | 25% | hardcoded secrets, committed .env, eval/exec, declared dependencies |
| 🫀 Liveness | 20% | project exists, git present, recent commits, not deprecated |
| 🔌 Protocol | 20% | detectable entrypoint, declared tools, valid mcp.json, documented transport, live handshake |
| 🧰 Usability | 20% | README, install steps, runnable example, clear value prop, config example |
| 📚 Docs | 15% | license, substantive README, examples, changelog, contributing guide |
Grades: A ≥ 90 · B ≥ 80 · C ≥ 65 · D ≥ 50 · F < 50.
🤝 Contributing
Contributions are welcome! See CONTRIBUTING.md. Add a check in mcp_grade/checks/, add a test, open a PR. Ready to ship? See LAUNCH.md.
📄 License
MIT © 2026 Md. Torikul Islam Lipon.
Metadata
Release files for mcp-grade 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_grade-1.0.0.tar.gz | 95.7 kB | Without provenance | Details for mcp_grade-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_grade-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_grade-1.0.0-py3-none-any.whl |
Total release size: 119.0 kB
Release files / mcp_grade-1.0.0.tar.gz
| Download URL | mcp_grade-1.0.0.tar.gz |
|---|---|
| Size | 95.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cd4d5ed50534792d522afbad78dd60797a393e4743e611a0076d865d2aee41e3
|
|
BLAKE2b-256 checksum How to use checksums |
e56c9cf032a902016447eecfa254bb4fd027aa2f9da3a61adf504963d80fc914
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / mcp_grade-1.0.0-py3-none-any.whl
| Download URL | mcp_grade-1.0.0-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
43198e409cf765b6a306b97387a0f2bbf4ba1904d948b70c33237bac07d98147
|
|
BLAKE2b-256 checksum How to use checksums |
35196e96337ed10809198bd134da7a16cb72c5630ed4390b95c50d6c57886c8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for mcp-grade 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.