# @aiwerk/mcp-catalog

Searchable directory of MCP server recipes, served as an MCP server. Any AI agent can discover, inspect, and download MCP server configs natively — through tool calls.

Works with **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **OpenClaw**, **MCP Bridge**, or any MCP client.

## Why?

Setting up MCP servers means finding the right package, writing config JSON, figuring out env vars. Every time.

**MCP Catalog** makes this discoverable:
- **4 MCP tools**: search, info, download, activate — all callable by AI agents
- **Weighted search**: name, keywords, description, tool names, tags — all scored and ranked
- **12 pre-seeded servers**: popular MCP servers ready to go
- **Multi-language keywords**: English + German (more coming)
- **Two transports**: stdio (default) or Streamable HTTP

## Install

```bash
npm install -g @aiwerk/mcp-catalog
```

## Quick Start

```bash
# 1. Seed the catalog with built-in recipes
mcp-catalog seed

# 2. Start (stdio mode — connects to any MCP client)
mcp-catalog
```

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "catalog": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-catalog"]
    }
  }
}
```

## Use with Cursor / Windsurf

Add to your MCP config:

```json
{
  "mcpServers": {
    "catalog": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-catalog"]
    }
  }
}
```

## Use with MCP Bridge

Add to your `~/.mcp-bridge/config.json`:

```json
{
  "servers": {
    "aiwerk-catalog": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-catalog"],
      "description": "MCP server catalog — searchable directory of MCP server recipes"
    }
  }
}
```

## MCP Tools

### `catalog_search`

Search for MCP servers by keyword, category, or transport type.

```json
{
  "query": "payment",
  "category": "finance",
  "transport": "stdio"
}
```

Returns ranked results:

```json
{
  "results": [
    {
      "name": "stripe",
      "description": "payments & billing",
      "category": "finance",
      "badges": ["stdio", "auth-required"],
      "transport": "stdio",
      "authRequired": true,
      "authType": "api-key",
      "downloads": 42
    }
  ]
}
```

### `catalog_info`

Get full recipe details for a specific server.

```json
{ "name": "stripe" }
```

Returns complete config: command, args, env vars, credentials URL, homepage, keywords, tool names, and more.

### `catalog_download`

Download a server recipe (returns full config JSON + increments download counter).

```json
{ "name": "github" }
```

### `catalog_activate`

Activate a server on the hosted bridge (coming in Phase 4).

```json
{ "name": "todoist" }
```

## Search Scoring

Results are ranked by weighted scoring across multiple fields:

| Match type | Weight | Example |
|-----------|--------|---------|
| Exact name | 1.0 | `"github"` → github server |
| Name prefix | 0.9 | `"goo"` → google-maps |
| Keyword | 0.8 | `"zahlungen"` → stripe, wise |
| Description | 0.6 | `"web scraping"` → apify |
| Tool name | 0.5 | `"issues"` → github |
| Tag | 0.4 | `"productivity"` → todoist, linear, miro |

Category aliases also work: searching `"developer"` filters to developer-tools category.

## Pre-seeded Servers

| Server | Category | Transport | Auth |
|--------|----------|-----------|------|
| apify | search | streamable-http | API key |
| github | developer-tools | stdio | API key |
| google-maps | maps | stdio | API key |
| hetzner | cloud | stdio | API key |
| hostinger | hosting | stdio | API key |
| linear | productivity | stdio | API key |
| miro | productivity | stdio | API key |
| notion | productivity | stdio | API key |
| stripe | finance | stdio | API key |
| tavily | search | stdio | API key |
| todoist | productivity | stdio | API key |
| wise | finance | stdio | API key |

## Transports

| Transport | Flag | Default port | Use case |
|-----------|------|-------------|----------|
| stdio | _(default)_ | — | Local MCP client integration |
| Streamable HTTP | `--http` | 3100 | Remote / multi-client access |

```bash
mcp-catalog              # stdio mode
mcp-catalog --http       # HTTP server on port 3100
```

## Tech Stack

- **TypeScript** + Node.js
- **SQLite** (better-sqlite3) with **FTS5** for full-text search
- **MCP SDK** (@modelcontextprotocol/sdk)
- **Zod** for parameter validation

## Development

```bash
git clone https://github.com/AIWerk/mcp-catalog.git
cd mcp-catalog
npm install

# Seed the database
npm run seed

# Run tests (21 tests)
npm test

# Dev mode
npm run dev

# Build
npm run build
```

## Architecture

```
┌─────────────────┐     ┌──────────────────────────────────────┐
│  Claude Desktop  │     │  MCP Catalog                         │
│  Cursor          │◄───►│                                      │
│  MCP Bridge      │stdio│  ┌────────────┐  ┌───────────────┐  │
│  Any MCP client  │ or  │  │ 4 MCP Tools│  │ SQLite + FTS5 │  │
│                  │http │  │            │──│               │  │
└─────────────────┘     │  │ search     │  │ 12 recipes    │  │
                        │  │ info       │  │ weighted      │  │
                        │  │ download   │  │ scoring       │  │
                        │  │ activate   │  │               │  │
                        │  └────────────┘  └───────────────┘  │
                        └──────────────────────────────────────┘
```

## Related

- **[@aiwerk/mcp-bridge](https://github.com/AIWerk/mcp-bridge)** — Multiplex multiple MCP servers into one interface
- **[@aiwerk/openclaw-mcp-bridge](https://github.com/AIWerk/openclaw-mcp-bridge)** — OpenClaw plugin for MCP Bridge
- **[MCP Specification](https://spec.modelcontextprotocol.io)** — Model Context Protocol spec

## License

MIT — [AIWerk](https://aiwerk.ch)