mcpfinder

# MCPfinder

> The MCP server that helps AI agents discover, evaluate, and install other MCP servers.

MCPfinder is an AI-first discovery layer over the Official MCP Registry, Glama, and Smithery. Install it once, and your assistant can search for missing capabilities, inspect trust signals, review required secrets, and generate client-specific MCP config snippets.

## Canonical Use

- Canonical transport: `stdio` via `npx -y @mcpfinder/server`
- Canonical package: [`@mcpfinder/server`](https://www.npmjs.com/package/@mcpfinder/server)
- MCP Registry entry: [`dev.mcpfinder/server`](https://registry.modelcontextprotocol.io/v0/servers?search=dev.mcpfinder)
- Public HTTP endpoint: intentionally not advertised as canonical until its tool surface is fully identical to the local server

## Quick Install

### Claude Desktop

```json
{
  "mcpServers": {
    "mcpfinder": {
      "command": "npx",
      "args": ["-y", "@mcpfinder/server"]
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "mcpfinder": {
      "command": "npx",
      "args": ["-y", "@mcpfinder/server"]
    }
  }
}
```

### Claude Code

```json
{
  "mcpServers": {
    "mcpfinder": {
      "command": "npx",
      "args": ["-y", "@mcpfinder/server"]
    }
  }
}
```

Supported install targets today:

- Claude Desktop
- Cursor
- Claude Code
- Cline / Roo Code
- Windsurf

### Install via Agent Skill (let your AI do it)

If your agent supports the [Agent Skills](https://agentskills.io) format
(Claude Code, GitHub Copilot in VS Code, OpenAI Codex, and others), you can
drop a one-line install and let the agent handle the config merge itself.

**Claude Code (global):**

```bash
mkdir -p ~/.claude/skills/install-mcpfinder && \
  curl -sSf -o ~/.claude/skills/install-mcpfinder/SKILL.md \
    https://mcpfinder.dev/skill/install-mcpfinder/SKILL.md
```

**VS Code (project-scoped):**

```bash
mkdir -p .agents/skills/install-mcpfinder && \
  curl -sSf -o .agents/skills/install-mcpfinder/SKILL.md \
    https://mcpfinder.dev/skill/install-mcpfinder/SKILL.md
```

Then tell your agent any of: *"install MCPfinder"*, *"connect my AI to
Postgres"*, *"I need a tool for [anything]"* — the skill activates, detects
your client, merges the config without clobbering, and tells you what to
restart.

## For AI Assistants

Use MCPfinder when the user needs a capability you do not already have.

- If the user mentions Slack, Postgres, GitHub, Notion, AWS, Google Drive, filesystems, browsers, APIs, or databases: call `search_mcp_servers`.
- Before recommending a server: call `get_server_details`.
- Before telling the user what to paste into config: call `get_install_config`.
- If the user only knows a domain, not a specific technology: call `browse_categories` (omit `category` to list; pass `category` for top servers).

Preferred workflow:

1. `search_mcp_servers(query="postgres")`
2. `get_server_details(name="...best candidate...")`
3. `get_install_config(name="...best candidate...", platform="claude-desktop")`
4. Tell the user what server you chose, why, which secrets are required, and what restart/reload step is needed.

## Tool Surface

| Tool | Purpose | When to call |
| --- | --- | --- |
| `search_mcp_servers` | Search by keyword, technology, or use case | First step when a capability is missing |
| `get_server_details` | Inspect metadata, trust signals, tools, warnings, env vars | Before recommending or installing |
| `get_install_config` | Generate a JSON config snippet for a target client | After selecting a server |
| `browse_categories` | Single-call category browser (omit `category` to list; pass `category` for top servers) | Domain-driven discovery |

## What MCPfinder Returns

MCPfinder is intentionally optimized for agent consumption.

- Human-readable text summaries
- Structured content for chaining follow-up calls
- Trust signals: source count, verification, popularity, recency
- Warning flags: stale projects, missing repository URL, unclear install path, single-source-only
- Install metadata: config snippet, target file paths, required environment variables, restart instructions

## Ranking and Recommendation

Search ranking uses:

- text relevance
- name-match boost — measured against the name with its *hosting prefix* removed
  (`io.github.<owner>/<repo>` → `<owner>/<repo>`, `ai.smithery/<slug>` →
  `<slug>`). That leading segment is a reverse-DNS namespace assigned by the
  Official registry to say where the server's code is hosted — `io.github.*`
  servers all come from Official, not from some "GitHub" registry — and it says
  nothing about what the server does. 19.6% of the catalog is named
  `io.github.%`, so scoring it turned the boost into a constant and buried every
  real match. The owner segment stays, so searching by owner still works. There
  is no way to search *by* the hosting namespace: `registrySource` filters on
  the registries an entry was found in (`official`/`glama`/`smithery`), which is
  a different thing.
- community usage (`useCount`)
- official registry presence
- verification signals

Each result is also annotated with:

- `confidenceScore`
- `recommendationReason`
- `warningFlags`
- `updatedAt`
- `sourceCount`

## Data Sources

MCPfinder aggregates:

- [Official MCP Registry](https://registry.modelcontextprotocol.io)
- [Glama](https://glama.ai/mcp/servers)
- [Smithery](https://smithery.ai)

Counts vary over time and differ depending on whether you count raw upstream records or merged/deduplicated entries. Snapshot metadata is the source of truth for the currently published local bootstrap dataset.

## Snapshots and Freshness

First run can bootstrap from a prebuilt SQLite snapshot instead of doing a slow live sync.
Normal startup therefore does not wait for all live registry budgets. The
sequential Official → Glama → Smithery cold crawl is a fallback for an empty DB
only when snapshot bootstrap is disabled or fails, preserving deterministic
cross-registry deduplication.

The download runs in the background: the MCP server answers `initialize`
immediately, tool calls arriving before the catalog exists — during the download
and during the handle switch alike — get a "still preparing" notice with progress
(`status: "preparing"`, distinct from a not-found result), and the verified file
is switched in without a restart. A
freshly installed snapshot counts as a fresh sync, so it does not immediately
trigger the live crawl it was meant to replace.

Each snapshot is stored as its own immutable file, `data-<sha16>.db`, selected
by a pointer at `data.db.snapshot.json`. Nothing is replaced in place, so the
several MCP clients that each run their own mcpfinder process against
`~/.mcpfinder` never pull a database out from under one another; superseded
files are swept only after `MCPFINDER_SNAPSHOT_RETAIN_HOURS` (default 48) of
being un-pointed-to and untouched, and the sweep unlinks the database file
alone — never its `-wal`/`-shm`, which a peer that still has the file open looks
up by name. That rule is unconditional: an orphaned journal, one whose database
is already gone, is left alone too, because nothing distinguishes it from the
journal of a peer that outlived its own file, and deleting the latter is
corruption. What keeps the residue small is that every successful sync ends with
`PRAGMA wal_checkpoint(TRUNCATE)`; the 40MB `-wal` measured beside a 323MB
database came from a single-transaction crawl whose journal was never trimmed at
all. What is left is a bounded leak after processes killed with `SIGKILL` — how
MCP clients usually stop stdio servers. Two limits follow: a removal is allowed
to fail — on the platforms and filesystems where an open file's name cannot be
taken away, stale snapshots stay until nothing holds them — and a journal can
outlive the database it belonged to. The install is re-checked daily: one
manifest request when nothing changed, plus a request for the DB when the
manifest advertises a newer digest — conditional (ETag) on the gzip endpoint,
unconditional on the brotli one, which is content-addressed by its own digest
and for which no ETag is ever recorded.

- snapshot manifest: `/api/v1/snapshot/manifest.json`
- snapshot database (gzip): use `manifest.url` (`data.sqlite.gz?sha=<sha256>`) as the content-addressed primary endpoint
- snapshot database (brotli): use `manifest.brotli.url` (`data.sqlite.br?sha=<brotli sha256>`)
- durable current fallback: `/api/v1/snapshot/data.sqlite.gz`, refreshed only after manifest publication
- scheduled build: [`.github/workflows/snapshot.yml`](.github/workflows/snapshot.yml)
- staleness monitor: [`.github/workflows/snapshot-staleness.yml`](.github/workflows/snapshot-staleness.yml)

### Two compressions of one database

Every build publishes the same SQLite file twice — gzip always, brotli when
that half of the pipeline succeeds (see the publication section below). Brotli
(quality 9, 16MB window) is about 21% smaller: measured at 36.8MB against
46.7MB gzip for the 238MB / 84,647-server database published on 2026-08-26.
Both figures scale with the corpus, so treat the manifest's `sizeBytes` and
`brotli.sizeBytes` as the live numbers rather than these. Compressing the
second artifact costs well under a minute of build time inside a 90-minute job,
and decompression is a fraction of a second. zstd compresses a further ~2MB but
needs Node 22.15+/23.8+. The 22.x floor now clears that bar, but Node 23.0-23.7
does not, so a third artifact would still have to carry a fallback for the gain
to be safe — not worth it while brotli already does the work.

```jsonc
{
  "publishedAt": "…", "serverCount": 84647,
  // gzip: the snapshot's identity — recorded in the client's pointer and
  // compared on every freshness check. Unchanged, and always published.
  "sha256": "<gz digest>", "sizeBytes": 46706108, "url": "data.sqlite.gz?sha=<gz digest>",
  // brotli: optional, additive, with its own digest and size. Absent whenever
  // the artifact could not be built, uploaded or verified.
  "brotli": { "u