# awesome-repositories.com — MCP server

> Point any MCP-aware agent at `https://awesome-repositories.com/api/mcp`. Walk through a one-click sign-in with Google on the first tool call; after that your agent can search the directory by intent, read any repository, and find its documentation. It's a read-only server.

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/).**

## Endpoint

- URL: `https://awesome-repositories.com/api/mcp`
- Transport: MCP Streamable HTTP, protocol `2025-06-18`
- Auth: OAuth 2.1 with Dynamic Client Registration (no static token to paste)

## Connect the server — one command, every agent

Adds the server to every MCP client it detects (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex, Zed, Goose, Copilot CLI, …):

```sh
npx add-mcp https://awesome-repositories.com/api/mcp --name awesome-repositories
```

Append `-y` to skip prompts, `-g` for a global install, or `--agent <client>` to target one.

### Per client

- **Claude Code:** `claude mcp add --transport http awesome-repositories https://awesome-repositories.com/api/mcp`
- **VS Code:** `code --add-mcp '{"name":"awesome-repositories","type":"http","url":"https://awesome-repositories.com/api/mcp"}'`
- **Cursor / Codex / Windsurf / Zed:** `npx add-mcp https://awesome-repositories.com/api/mcp --agent cursor` (swap in `codex`, `windsurf`, `zed`, …)
- **Claude Desktop / any other client:** paste the JSON block below into its MCP config.

```json
{
  "mcpServers": {
    "awesome-repositories": {
      "type": "http",
      "url": "https://awesome-repositories.com/api/mcp"
    }
  }
}
```

No Authorization header — the client handles the OAuth flow for you.

## Authentication

Auth is OAuth 2.1. Clients auto-discover the authorization server from `https://awesome-repositories.com/.well-known/oauth-protected-resource`, register themselves, then open a browser tab so the user can sign in with Google. Refresh tokens keep the session alive.

This is a read-only server — every signed-in user can call every tool. Curation is done by maintainers through a separate admin CLI, never over this transport.

## Optional — install the search skill

```sh
npx skills add https://awesome-repositories.com
```

Resolves via the agent-skills well-known index at `https://awesome-repositories.com/.well-known/agent-skills/index.json` and installs the search workflow into every detected agent. Powered by [skills.sh](https://skills.sh).

## Tools (all read-only)

- `search_repositories` — hybrid BM25 + AI search (AI on by default; `ai:false` for raw BM25); narrow with `filter_tag_paths`.
- `search_metadata_tags` — hybrid search over the unified tag tree; resolve a concept to a canonical tag path.
- `get_repository` — full detail by internal id or `owner/repo`, with tag assignments and doc counts.
- `list_curated_searches` — admin-pinned search slugs.
- `list_repository_docs` — the documentation pages indexed for a repository, each with its source URL. Fetch a page's body directly from that URL.