Audits an MCP server and returns a 0–100 score with cited, fixable findings on protocol, tools, and security.
Also known as mcp-box/mcpscore, @mcp-box/mcpscore
- Stars
- 43
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is mcpscore MCP?
mcpscore audits an MCP server and returns a 0–100 score with cited, fixable findings on protocol, tools, and security.
Summary generated from the project's README
About mcpscore MCP server
Auditing Model Context Protocol servers for quality and security is what mcpscore enables for developers building tools for AI agents. It evaluates servers against a set of rules covering protocol adherence, tool primitives, security, and authentication. The tool provides a numerical score from 0 to 100 and identifies specific, fixable issues cited from the MCP spec, RFCs, or established best practices.
Developers can run audits against remote URLs or local servers using stdio transport. The system supports authenticated endpoints via tokens, custom headers, or OAuth flows. It can be integrated into CI/CD pipelines using a GitHub Action to fail builds if a score drops below a defined threshold. For those using coding agents like Claude Code, a plugin is available to automatically attempt fixes for discovered findings. It also includes a smoke test mode to verify that tools actually function as expected during execution.
What you can do with it
- 1Verify server quality in CIAutomatically fail a pull request if a server's quality score falls below a specific percentage.
- 2Fix security vulnerabilitiesIdentify risks like improper origin validation that could allow malicious web pages to interact with your server.
- 3Test tool functionalityRun smoke tests to ensure that the tools provided by your server respond correctly to calls.
- 4Automate code repairsUse a coding agent to detect errors in your MCP server and apply fixes directly to the source code.
Written from the project's README. Every use case is checked against a quote from it.
How to install mcpscore MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall mcpscore MCP in Claude Code
$ claude mcp add mcpscore -- npx -y @mcp-box/mcpscoreInstall mcpscore MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcpscore": {
"command": "npx",
"args": [
"-y",
"@mcp-box/mcpscore"
]
}
}
}Install mcpscore MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcpscore": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mcp-box/mcpscore"
]
}
}
}Install mcpscore MCP in VS Code CLI
$ code --add-mcp '{"name":"mcpscore","type":"stdio","command":"npx","args":["-y","@mcp-box/mcpscore"]}'Install mcpscore MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcpscore": {
"command": "npx",
"args": [
"-y",
"@mcp-box/mcpscore"
]
}
}
}Install mcpscore MCP in Codex
$ codex mcp add mcpscore -- npx -y @mcp-box/mcpscoreInstall mcpscore MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcpscore] command = "npx" args = ["-y", "@mcp-box/mcpscore"]
Install mcpscore MCP in Gemini CLI
$ gemini mcp add -s user mcpscore npx -- -y @mcp-box/mcpscoreInstall mcpscore MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcpscore": {
"command": "npx",
"args": [
"-y",
"@mcp-box/mcpscore"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubmcpscore
Lighthouse for MCP. Point mcpscore at an MCP server and get a score plus a list of what to fix, each finding cited to its source: the MCP spec, an RFC, the MCP Registry schema, or a stated best practice.
A missing tool title, a stale protocol version, or an endpoint that accepts
any Origin never crashes your server. It makes agents pick the wrong tool,
or lets a malicious web page talk to your server. mcpscore finds those before
your users do. It is deterministic and needs no API key and no sign-up.
Documentation: docs.mcpscore.dev
Install
pip install mcpscore
With uv, uvx mcpscore runs it without installing. Node users can run
npx @mcp-box/mcpscore with uv or pipx on PATH; the npm package launches
this Python engine (npm setup).
Audit your first server
mcpscore https://mcp.deepwiki.com/mcp
Welcome to mcpscore!
Successfully connected to MCP server via Streamable HTTP: https://mcp.deepwiki.com/mcp
Transport: streamable-http
Starting the audit...
✅ Protocol version "2025-11-25" is one of the allowed versions.
❌ Server title is not present in server info. This is an optional quality recommendation. First affected field: server "/serverInfo/title".
Fix: Add a human-readable serverInfo.title so clients can display a recognizable server name.
✅ Server uses HTTPS with valid TLS (TLSv1.3).
❌ Streamable HTTP does not reject an invalid foreign Origin with HTTP 403, risking DNS rebinding. Observed HTTP status: 200.
Fix: Validate supplied Origin headers against the origins allowed for this endpoint. Return HTTP 403 for invalid origins; do not allow every origin to satisfy browser requests.
...
Audit finished. Final score: 96/114
Spec: 2025-11-25 negotiated (latest: 2026-07-28) · era: legacy
Readiness for MCP 2026-07-28: 3/13 (informative — not part of the main score; 4 of 22 checks assessed)
That's it. The server has a score.
Each ✅ or ❌ is one rule: one check, like security_origin_validation, that
passed or failed. Every ❌ carries a Fix: line. 96/114 means the server
earned 96 of the 114 points its rules can award. Rules that cannot apply to
this server are skipped and left out of the 114, so a server is never
penalized for a feature it does not have.
Audit a server on your machine
A local server is audited the same way as a URL: put the script where the URL was.
mcpscore path/to/server.py
Transport: stdio
...
Audit finished. Final score: 140/164
Spec: 2025-11-25 negotiated (latest: 2026-07-28) · era: dual-era
Python and Node scripts are detected by extension. For any other language,
or a Python server in its own environment, name the command after --stdio:
mcpscore --stdio ./my-go-server
mcpscore --stdio uv run server.py
--stdio consumes the rest of the line, so put every other option before it.
More: audit a local server.
Audit a server behind auth
mcpscore https://your-server.example/mcp --token "$TOKEN"
Without a credential, an auth-gated server still gets a partial score for its
auth, TLS, and transport surface. --oauth opens the browser instead of
taking a token, and --header sends an API-key header.
More: authenticated servers.
Let your coding agent fix it
The mcpscore plugin lets Claude Code or Codex run the audit, fix the findings in your own server code, and re-audit to show the score before and after:
/plugin install mcpscore --marketplace mcp-box/mcpscore-plugin
Audit my MCP server in server.py and fix what you safely can
More: use from your coding agent.
Fail the build when the score drops
mcpscore https://your-server.example/mcp --fail-under 90
When the score is below the threshold, the last line says so and the exit
code is 3:
Audit finished. Final score: 96/114
...
Gate failed — --fail-under 90: score 96/114 (84%) is below the required 90%
A refactor that drops a tool description now fails the pull request instead of reaching someone's agent. On GitHub, the Action runs the same gate and posts the report as a pull request comment:
- uses: mcp-box/mcpscore-action@v1
with:
target: https://your-server.example/mcp
min-score: 80
--json writes the full report to stdout and --sarif FILE writes failed
rules for GitHub code scanning.
More: GitHub Action,
other CI systems.
Check that your tools actually work
--smoke runs the audit, then calls your server's tools and checks how they
answer:
mcpscore --smoke path/to/server.py
Smoke checks (tools/call): 0 passed, 1 failed, 2 skipped — only readOnlyHint: true tools called (see --call-all). Never counted in the score.
skip smoke_structured_content [add]: not called under the safety default (readOnlyHint is not true); pass --call-all to include it
...
FAIL smoke_unknown_tool: reported a tool execution error (isError) for a nonexistent tool — the spec's unknown-tool example is a protocol error, and an isError result claims the tool exists and ran
Gate failed — --smoke: 1 smoke check(s) failed
A failed smoke check exits 4 and never changes the score. By default only
tools annotated readOnlyHint: true are called; --call-all includes the
rest, so use it only on a server you own.
More: smoke mode.
Turn off or re-rank rules
Put an mcpscore.toml next to your code:
[rules]
server_websiteurl_present = "off" # does not run
tools_title_present_in_all = "critical" # counts as CRITICAL
[gate]
fail_on = "high" # exit 3 on any failed rule at HIGH or above
The CLI finds it by walking up from the current directory, and also reads
[tool.mcpscore] in pyproject.toml. It changes the score in your
runs only; the website and the badge always use the defaults.
More: configure rules.
Show the score in your README
Audit the server once on mcpscore.dev and embed its badge. It always shows the latest score.
[](https://mcpscore.dev/s?url=https%3A%2F%2Fyour-server.example%2Fmcp)
More: score badge.
Score a published package
mcpscore --package pypi:mcpscore
📦 Auditing package pypi:mcpscore
Resolved version: 1.20.0
✅ Package "mcpscore" is published on pypi.
✅ Source repository declared: "https://github.com/mcp-box/mcpscore".
...
Audit finished. Final score: 16/16
Packaging audit of pypi:mcpscore — metadata only, the package was not downloaded or run.
This scores the npm or PyPI listing from registry metadata, on its own scale. More: package audits.
Exit codes
| Exit code | Meaning |
|---|---|
0 |
The audit completed and every gate passed |
1 |
The audit never ran: a usage error or a failed --oauth flow |
2 |
mcpscore could not connect to the server |
3 |
--fail-under, --fail-under-readiness, or [gate] was not met |
4 |
A --smoke check failed (3 wins when both fail) |
What the score measures
144 server rules in four categories:
- Protocol: protocol version, server identity, capabilities, transport.
- Primitives: tools, prompts, resources, resource templates, and skills served over the Skills extension. Names, titles, descriptions, schemas, annotations, and pagination decide whether an agent picks the right tool and calls it correctly.
- Security & Auth: TLS,
Originvalidation, error responses that leak data, and for auth-gated servers the OAuth challenge and metadata chain. - Readiness: how ready the server is for the 2026-07-28 spec revision. It counts in the main score for servers already on the new stateless lifecycle and is guidance for the rest.
Each rule has a severity: CRITICAL is worth 5 points, HIGH 3, MEDIUM 2,
LOW 1. Six more rules score packages under --package.
More: scoring methodology,
every rule,
what is stable between releases.
When it fails
Error connecting to the MCP server: https://... (exit 2)
- Cause: the URL answered, but not as an MCP endpoint.
- Fix: point at the MCP endpoint itself, usually ending in
/mcp.
'server.py' is a script, not an executable command (exit 2)
- Cause:
--stdioruns a program, and a bare script is looked up onPATH. - Fix: name the interpreter:
--stdio uv run server.py.
Audit finished. PARTIAL score: ... — not comparable to a full audit.
- Cause: the server answered 401 and you passed no credential.
- Fix: pass
--token,--header, or--oauth.
More: troubleshooting.
Requirements
- Python 3.11 or newer.
- For local servers, the server's own runtime on
PATH: Python for.py, Node.js for.js, and whatever--stdionames for the rest.
Use as a library
The package is fully typed (py.typed). MCPClient connects and collects,
and MCPAuditor runs the rules and builds the same report the CLI prints.
The --json report shape is versioned by schema_version, and rule_id
values are stable across releases.
Contributing
CONTRIBUTING.md covers the development setup and how to add a rule. MISSION.md says why the project exists, and SECURITY.md is for security reports. Every release is in the CHANGELOG. Bugs and ideas go to GitHub issues.
License
MIT. See LICENSE.
mcpscore MCP questions
How do I add mcpscore MCP to Claude Code?
Run claude mcp add mcpscore -- npx -y @mcp-box/mcpscore in your terminal. Add --scope user to make it available in every project.
How do I add mcpscore MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I audit a remote MCP server with mcpscore?
Pass the server's MCP endpoint URL to the CLI, which connects over Streamable HTTP and runs the full rule set.
Does mcpscore need an API key or sign-up?
No. The audit is deterministic and requires no API key and no account.
Can mcpscore fail a CI build when the score drops?
Yes. Use --fail-under to set a threshold; the run exits with code 3 when the score is below it, and a GitHub Action posts the report as a PR comment.
Can I audit a local stdio MCP server script?
Yes. Point mcpscore at a .py or .js file, or name the command after --stdio for other languages and custom environments.
Does mcpscore test that the tools actually work?
With --smoke it calls the server's tools and checks their responses, but smoke results never change the score and a failure exits with code 4.