mcp-lock

npm ci for your MCP servers.

Every time your AI coding tool starts, npx -y @scope/mcp-server silently downloads the latest version of every MCP server. No version pin. No hash check. No record of what ran yesterday.

mcp-lock fixes this. It records the exact version and tarball integrity hash of every MCP server on first run, and verifies nothing changed on every run after that.

The problem

// Your .mcp.json — right now
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
      //        ^^^
      //        Downloads whatever is latest. Every. Single. Time.
    }
  }
}

The March 2026 axios supply chain attack compromised a minor version bump (1.14.1). Everyone using ^1.14.0 silently auto-upgraded. The malware ran before anyone noticed.

MCP servers face identical risk. They're npm packages. They run with your credentials. They access your filesystem and APIs. And no existing scanner tracks whether the package you're running today is the same one you reviewed last week.

Install & quick start

# 1. Lock all your MCP servers (one time)
npx @mcpguards/mcp-lock init

# 2. Commit the lockfile
git add .mcp.lock && git commit -m "chore: add mcp-lock lockfile"

# 3. Verify on every CI run (exits 1 if anything changed)
npx @mcpguards/mcp-lock verify

That's it. If a package changes between runs, you'll know before your AI agent runs it.

Commands

mcp-lock init

Discovers all MCP configs on your machine, resolves each server to its npm package, records the exact version + tarball integrity hash.

$ mcp-lock init

Found 4 server(s) across 2 config(s)

  ✔ filesystem      2026.1.1            sha512-xK3z…  ✔ attestation
  ✔ github          2026.1.1            sha512-9mRq…  ✔ attestation
  ✔ memory          2025.11.18          sha512-pL2t…  ○ no attestation
  ~ python-server   pypi registry — not lockable

─────────────────────────────────────────────────────────────────
  3 locked  1 skipped

✔ Lockfile written to .mcp.lock
Tip: Run with --pin to add version pins to your MCP configs.

Options:

--config <path>   Scan a specific config file
--pin             Rewrite configs to add @version pins
--force           Overwrite existing lockfile
--global          Write to ~/.mcp.lock

mcp-lock verify

Compares your installed packages against the lockfile. Exits 1 if anything changed.

$ mcp-lock verify

mcp-lock  .mcp.lock
────────────────────────────────────────────────────────────────
  ✔ filesystem
  ✔ github
  ⚠ memory  INTEGRITY-CHANGED
      integrity    sha512-pL2t…  →  sha512-XXXX…
      version      2025.11.18   →  2025.11.19
      ACTION REQUIRED: Run `mcp-lock update memory` after manual review.

────────────────────────────────────────────────────────────────
  2 clean  1 changed  0 skipped

✖ 1 server(s) changed since last lock.
  Run 'mcp-lock update <server>' to review and accept changes.

Options:

--sarif <path>    Write SARIF 2.1.0 report for GitHub Security tab
--json            Output as JSON
--global          Check against ~/.mcp.lock

Exit codes: | Code | Meaning | |------|---------| | 0 | Clean — all servers match the lockfile | | 1 | Changed — one or more servers changed, or lockfile tampered | | 2 | Lockfile missing — run mcp-lock init | | 3 | Network / registry error | | 4 | Invalid arguments |

mcp-lock update <server>

Shows exactly what changed, asks for confirmation, updates the lockfile.

$ mcp-lock update memory

  memory
  version      2025.11.18 → 2025.11.19
  integrity    sha512-pL2t… →
               sha512-XXXX…

Accept update for memory? [y/N] y
✔ Updated 1 server(s) in .mcp.lock

Options:

--all             Update all servers
--to <version>    Update to a specific version
--yes             Skip confirmation prompt (for CI)
--pin             Also update version pin in the MCP config

mcp-lock list

Shows all locked servers.

$ mcp-lock list

mcp-lock list  scope: project
────────────────────────────────────────────────────────────────
  ✔ filesystem      @modelcontextprotocol/server-filesystem    2026.1.1
  ✔ github          @modelcontextprotocol/server-github        2026.1.1
  ○ memory          @modelcontextprotocol/server-memory        2025.11.18
────────────────────────────────────────────────────────────────
  3 servers  generated 4/16/2026

GitHub Action

Add to any repo that has a .mcp.json config. Fails the PR if a server changed without an explicit mcp-lock update:

# .github/workflows/mcp-lock.yml
name: MCP Lock
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # for SARIF upload
    steps:
      - uses: actions/checkout@v4

      - uses: mcpguards/[email protected]
        with:
          sarif-output: mcp-lock.sarif

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp-lock.sarif

Findings appear in the Security → Code Scanning tab:

mcp-lock: server 'memory' integrity changed
  The tarball integrity hash changed since last lock.
  Run: mcp-lock update memory

Action inputs: | Input | Default | Description | |-------|---------|-------------| | config-path | (auto-discover) | Path to MCP config | | fail-on-missing-lock | true | Fail if no lockfile exists | | sarif-output | (none) | Path to write SARIF report |

The lockfile

.mcp.lock is a JSON file you commit to your repository. It records:

{
  "lockfileVersion": 1,
  "generatedBy": "[email protected]",
  "generatedAt": "2026-04-16T12:00:00.000Z",
  "scope": "project",
  "servers": {
    "filesystem": {
      "source": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem"],
        "configPath": "/abs/path/.mcp.json"
      },
      "resolved": {
        "registry": "npm",
        "name": "@modelcontextprotocol/server-filesystem",
        "version": "2026.4.10",
        "tarball": "https://registry.npmjs.org/...tgz",
        "integrity": "sha512-AbC...==",
        "shasum": "a1b2c3...",
        "publishedAt": "2026-04-10T09:12:33.000Z"
      },
      "attestation": {
        "present": true,
        "predicateTypes": ["https://slsa.dev/provenance/v1"]
      },
      "lockedAt": "2026-04-16T12:00:00.000Z"
    }
  },
  "checksum": "sha256-9f86d081..."
}

The checksum field is a SHA-256 of the entire lockfile content (canonical JSON, sorted keys). If the file is manually edited without running mcp-lock update, verify will catch it.

Supported MCP clients

Auto-discovered on your machine:

| Client | Config path | |--------|-------------| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Code | ~/.claude/settings.json | | Cursor | ~/.cursor/mcp.json | | VS Code | ~/Library/Application Support/Code/User/settings.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Amazon Q | ~/.aws/amazonq/mcp.json | | Project-level | .mcp.json in current directory |

How it differs from other tools

| Tool | Checks npm packages | Integrity hash | Detects version changes | SBOM | Lockfile | |------|:-:|:-:|:-:|:-:|:-:| | Snyk Agent Scan | ❌ | ❌ | ❌ | ❌ | ❌ | | Cisco mcp-scanner | ❌ | ❌ | ❌ | ❌ | ❌ | | MCPWatch | ❌ | ❌ | ❌ | ❌ | ❌ | | mcp-lock | ✅ | ✅ | ✅ | ✅ | ✅ |

The others scan tool descriptions and configurations for prompt injection. mcp-lock treats MCP servers as software supply chain artifacts and applies package integrity verification — the same approach npm ci uses.

Requirements

• Node.js >= 18.3.0
• Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Amazon Q, and any tool using the MCP spec

License

MIT © Vamshidhar Reddy Parupally