# pkgtruth MCP server

> Prevents AI agents from installing hallucinated or malicious npm and PyPI packages by verifying package names against real registry data.

- Repository: https://github.com/hxckya/pkgtruth
- Page: https://hostedmcp.org/servers/hxckya/pkgtruth
- Transport: stdio
- Stars: 4
- License: MIT
- Latest version: 0.2.2

## Install

### Claude Code

```sh
claude mcp add pkgtruth -- npx -y pkgtruth
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "pkgtruth": {
      "command": "npx",
      "args": [
        "-y",
        "pkgtruth"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pkgtruth": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "pkgtruth"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pkgtruth","type":"stdio","command":"npx","args":["-y","pkgtruth"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "pkgtruth": {
      "command": "npx",
      "args": [
        "-y",
        "pkgtruth"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add pkgtruth -- npx -y pkgtruth
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.pkgtruth]
command = "npx"
args = ["-y", "pkgtruth"]
```

### Gemini CLI

```sh
gemini mcp add -s user pkgtruth npx -- -y pkgtruth
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "pkgtruth": {
      "command": "npx",
      "args": [
        "-y",
        "pkgtruth"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `PKGTRUTH_CACHE_DIR` | no | no | Where adoption figures are cached between runs. Defaults to ~/.cache/pkgtruth. |
| `PKGTRUTH_DOWNLOADS_API` | no | no | Alternate downloads API used for adoption figures. Defaults to https://api.npmjs.org. |
| `PKGTRUTH_REGISTRY` | no | no | Alternate npm registry to verify against. Defaults to https://registry.npmjs.org. |
| `PKGTRUTH_TIMEOUT_MS` | no | no | Per-request timeout in milliseconds. Defaults to 8000. |

## Tools (3)

- `check_package`: Verify a single npm or PyPI package before installing, importing, or recommending it. Returns whether it actually exists, and flags slopsquatting (a low-adoption package impersonating a popular one), names npm removed for malware, install-time scripts, deprecation, and abandonment. Call this whenever you are about to introduce a dependency you have not verified in this session. Read-only; one or two requests to the public registry. A verdict of UNKNOWN means the registry did not answer — retry, never assume safe. (read-only)
- `check_dependencies`: Verify many npm or PyPI packages at once — use this before writing a package.json or requirements.txt, or handing a dependency list to a user. All names must belong to one ecosystem per call. Results are sorted worst-first so anything hallucinated or dangerous surfaces at the top. Read-only; batches registry requests and caches adoption figures, so 50 names take a few seconds. (read-only)
- `check_install_command`: Verify the packages a shell command would install or execute, before running it: `npm install …`, `npx …`, `pnpm add`, `yarn add`, `bun add`, `pip install`, `uv add`, `poetry add` and similar, including behind `sudo`, `&&` chains and `sh -c`. Extracts the package names (npm and PyPI at once), checks each against its registry, and returns them worst-first. A command that installs nothing by name (a bare `npm install` from a lockfile, `git`, `npm test`, or `npx <bin>` of a tool already in node_modules) returns total 0 and costs no network call — use check_dependencies on the manifest in that case. Read-only. (read-only)

## FAQ

### What is slopsquatting?

Slopsquatting is a technique where attackers register package names that large language models frequently invent or hallucinate.

### Does pkgtruth analyze the actual source code of a package?

No, it only checks registry metadata and does not perform source code analysis.
