# Plugolis MCP server

Find MCP servers and fix MCP errors right from your AI assistant.

This server gives Cursor, Claude, VS Code and other MCP clients read-only access to the [Plugolis](https://plugolis.com) directory. That covers MCP servers with install commands and ready-to-paste configs, plus step-by-step fixes for common errors like `spawn npx ENOENT` or `MCP error -32000: Connection closed`.

- **Read-only.** It only reads Plugolis's public JSON API at `https://plugolis.com/api/`.
- **No API key, no account, no secrets.**
- Data is cached for 15 minutes, so repeated questions are fast.

## Tools

| Tool | What it does |
| --- | --- |
| `search_servers` | Search servers by words (`query`) and filter by `category`, `client` (e.g. Cursor), `status` (`maintained` / `stale`) and `transport` (`local` / `remote`). |
| `get_server` | Everything about one server (by slug): install command, config JSON, required env vars, repo, stars, maintenance status. |
| `list_categories` | All categories with their server counts. |
| `search_fixes` | Paste an error message to find the matching fix. You can filter by client. |
| `get_fix` | One fix in full: the error, the cause, numbered steps with code, and sources. |

Example prompts:
- "Find a maintained MCP server for Postgres and give me the Cursor config."
- "Claude Desktop says `spawn npx ENOENT`. How do I fix it?"

## Install

Requires [Node.js](https://nodejs.org) 18 or newer.

### Cursor

Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

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

### Claude Desktop

Open **Settings → Developer → Edit Config** and add this to `claude_desktop_config.json`, then restart Claude:

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

On Windows, if you see `spawn npx ENOENT`, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "plugolis-mcp"]`.

### Claude Code

```bash
claude mcp add plugolis -- npx -y plugolis-mcp
```

### VS Code

Add this to `.vscode/mcp.json`. Note that VS Code uses `servers`, not `mcpServers`:

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

### Remote server (coming soon)

A hosted version that needs no install is planned at `https://mcp.plugolis.com/mcp` (Streamable HTTP). **It is not live yet.** Use the `npx` setup above until this note is removed.

## Options

These environment variables are all optional:

| Variable | Default | Meaning |
| --- | --- | --- |
| `PLUGOLIS_API_URL` | `https://plugolis.com/api` | Where to read the data |
| `PLUGOLIS_CACHE_TTL_MS` | `900000` (15 min) | How long to cache it |

## Development

```bash
npm install
npm test              # builds, then runs the stdio server and calls every tool through a real MCP client
npm run test:worker   # runs the Cloudflare Worker with `wrangler dev` and calls every tool over HTTP
npm run typecheck
```

Set `SKIP_LIVE=1` to skip the tests that use the live plugolis.com API.

Project layout:
- `src/data.ts`: fetches the API, with caching, timeouts and clear errors
- `src/server.ts`: the MCP tools (shared by both versions)
- `src/index.ts`: the stdio entry point (`npx plugolis-mcp`)
- `workers/`: the remote Streamable HTTP version for Cloudflare Workers (stateless, endpoint `/mcp`)

You can also try it in the MCP Inspector:

```bash
npm run build && npx @modelcontextprotocol/inspector node dist/index.js
```

## Data and license

The data comes from [plugolis.com](https://plugolis.com). If you reuse it, credit Plugolis with a link. The code is released under the [MIT](LICENSE) license.