MCP Fingerprints & Passport Knowledge Base

An open-source, automated database and knowledge base of Model Context Protocol (MCP) server passports, version signatures, and tool contract fingerprints.

Ecosystem Architecture & Scope

mcp-fingerprints serves as the authoritative open standard for structural Model Context Protocol server passports. It focuses purely on:

• Static AST Extraction: Deep parameter schema, docstring, prompt, and resource extraction across Python, TypeScript/JavaScript, Go, and Rust.
• Deterministic Cryptographic Hashing: Order-invariant and whitespace-insensitive canonical hashing (canonical_hash, toolset_canonical_hash).
• Supply-Chain Verification & Drift Tracking: Detecting tool tampering, description changes, and schema mutations across package versions.
• Open Catalog & Client Exporters: Serving enriched structural web catalogs with interactive parameter schema inspectors and 1-click config generators.

Key Features

• 5,058+ Indexed Passports: Cross-indexed across Smithery, npm, PyPI, and GitHub registries.
• Deep Parameter & Annotation Extraction: Captures parameter types, descriptions, defaults, enums, required flags, and protocol annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
• Automated Daily Sync: Continuously crawls, extracts tool signatures, canonicalizes hash fingerprints, and tracks historical schema drift.
• Consolidated Snapshot: Pre-compiled passports.json.gz for rapid HTTP consumption (< 50ms startup time).

Quickstart: Search & Client Export

Search for available MCP servers:

python3 -m mcp_fingerprints.cli search "postgres"

Export an MCP server configuration for Claude Desktop:

python3 -m mcp_fingerprints.cli export-config @modelcontextprotocol/server-postgres --client claude

Export an MCP server configuration for Cursor:

python3 -m mcp_fingerprints.cli export-config @modelcontextprotocol/server-postgres --client cursor

Live Probing, Workstation Inventory & Drift Tracking

The Problem It Solves

Developers, SecOps analysts, and platform engineers often have dozens of MCP servers configured across Claude Desktop, Cursor, and Windsurf, or connecting AI agents to remote HTTP/SSE endpoints. Over time, teams lose track of:

• Identity & Provenance: What exact software package is running behind a command or URL, and where was it downloaded from?
• Shadow MCP Assets: Which MCP servers are quietly installed in developer configuration files?
• Silent Contract Drift: Did an automated package upgrade change tool descriptions or inject new parameters without notice?

mcp-fingerprints provides a complete detection and inventory suite available as both a CLI tool and an importable Python SDK.

1. Workstation MCP Inventory (scan-configs)

Automatically discovers configuration files across Claude Desktop (claude_desktop_config.json), Cursor (global ~/.cursor/mcp.json and project .cursor/mcp.json), and Windsurf, probes active servers, and determines their identities:

# Auto-discover and audit all local MCP configurations
mcp-fingerprints scan-configs --auto

# Export a consolidated JSON schema inventory of all local MCP tools
mcp-fingerprints scan-configs --auto --output mcp-inventory.json

Python SDK:

from mcp_fingerprints import scan_local_configs

inventory = scan_local_configs(probe_live=True)
for server in inventory.servers:
    print(f"[{server.client_name}] {server.server_name}: {server.package_name} ({server.version})")
    print(f"  Tools: {', '.join(t.name for t in server.tools)}")

2. Stateful Run-to-Run Drift Tracking (--compare-snapshot)

Establish a baseline snapshot of your local MCP tools and catch unauthorized modifications, deleted servers, or drifted tool contracts:

# 1. Save an initial baseline snapshot
mcp-fingerprints scan-configs --auto --save-snapshot mcp-baseline.json

# 2. Check for drift on subsequent runs (or in CI/CD pre-commit hooks)
mcp-fingerprints scan-configs --auto --compare-snapshot mcp-baseline.json --fail-on-drift

Sample Differential Drift Output:

======================================================================
               LOCAL MCP INVENTORY DRIFT REPORT
======================================================================
➕ ADDED SERVERS (1):
  • [Cursor] github-tools -> @modelcontextprotocol/server-github (v0.6.0)

🔄 MODIFIED / DRIFTED SERVERS (1):
  • [Claude] postgres -> @modelcontextprotocol/server-postgres
    - Version: 0.6.1 -> 0.6.2 (Upgraded)
    - Tool Contract Mutations:
      * 'read_query': Parameter 'timeout_ms' added (type: integer, optional)
======================================================================

3. Dual-Transport Live Probing & Attribution (stdio + http)

Connect to any live MCP server via local subprocess (stdio) or remote URL (http/sse), identify what it is, and retrieve its official repository and download instructions:

# Probe local server with concise 3-line summary
mcp-fingerprints probe --format short -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/db

# Probe remote HTTP/SSE endpoint
mcp-fingerprints probe --url http://localhost:8000/sse --format long

# Authenticated remote endpoint
mcp-fingerprints probe --url https://api.example.com/mcp --header "Authorization: Bearer mytoken"

Python SDK:

from mcp_fingerprints import identify_stdio, identify_http

# Identify local subprocess
report = identify_stdio(["uvx", "mcp-server-git"])
print(f"Verified: {report.package_name} ({report.repository_url})")

# Identify remote HTTP/SSE endpoint
remote = identify_http("https://mcp.internal.acme.com/sse")
print(f"Remote Server: {remote.package_name} v{remote.version}")

Enriched Tool Parameter Schemas & Protocol Annotations

MCP Fingerprints extracts rich parameter schemas and runtime protocol hints directly from server source ASTs:

• Structured Parameter Metadata: Includes parameter types (string, number, boolean, array, object), descriptions, required status, default values, and allowed enums.
• Protocol Annotations: Captures MCP tool behavior hints:
  • readOnlyHint: Tool performs read-only operations without side effects.
  • destructiveHint: Tool performs destructive operations (deletions, modifications).
  • idempotentHint: Repeated invocations yield identical state.
  • openWorldHint: Tool interacts with external/unconstrained network services.
• Transport Specifications: Captures supported transports (stdio, sse, streamable-http, websocket) and required environment variables.

Fast Consumption

You can fetch the latest consolidated database in a single GET request:

curl -sL https://raw.githubusercontent.com/JMartynov/mcp-fingerprints/main/passports.json.gz | gzip -d > passports.json

Python

import gzip, json, urllib.request

url = "https://raw.githubusercontent.com/JMartynov/mcp-fingerprints/main/passports.json.gz"
with urllib.request.urlopen(url) as resp:
    with gzip.GzipFile(fileobj=resp) as gz:
        data = json.load(gz)

print(f"Loaded {data['total_passports']} MCP server passports.")

CLI Usage

The CLI provides a focused set of pure structural commands:

# Sync from registries
python -m mcp_fingerprints.cli sync --all

# Match a toolset hash against the knowledge base
python -m mcp_fingerprints.cli match <hash>

# Probe a server and extract its fingerprint
python -m mcp_fingerprints.cli probe <server_command>

# Validate schema invariants
python -m mcp_fingerprints.cli validate --dir data/fingerprints

# Build compressed snapshot
python -m mcp_fingerprints.cli snapshot

# Search the catalog
python -m mcp_fingerprints.cli search "query"

# Browse interactively via TUI
python -m mcp_fingerprints.cli browse

# Export client configurations (Claude, Cursor, Cline, Zed, Windsurf)
python -m mcp_fingerprints.cli export-config <server_name> --client claude

# Detect configuration drift against the latest passports
python -m mcp_fingerprints.cli detect-drift <config_file>

Reporting & Output Formats

Customize the output verbosity to fit your terminal or CI environment:

# Concise 3-line summary for quick checks and CI logs
mcp-fingerprints probe --format short -- npx -y @modelcontextprotocol/server-sqlite --db app.db

# Exhaustive schema and parameter audit report
mcp-fingerprints probe --format long -- npx -y @modelcontextprotocol/server-sqlite --db app.db

# Structured JSON output for scripting and automation
mcp-fingerprints probe --json -- npx -y @modelcontextprotocol/server-sqlite --db app.db

Releases

TestPyPI Dry-Run

You can perform an automated dry-run release to TestPyPI to verify packaging, metadata, and functionality before a production PyPI release.

1. Navigate to the Actions tab in the GitHub repository.
2. Select the Release to TestPyPI (Dry-Run) workflow.
3. Click Run workflow.
4. You can optionally provide a version_suffix (e.g. rc1, b2) which will be appended to the current version in pyproject.toml to avoid conflicts on TestPyPI.
5. The workflow will build artifacts, publish them to TestPyPI using Trusted Publishing, and execute an automated smoke test (pip install into a clean container).

License

MIT