---
title: "GStars MCP server"
description: "Connect AI agents to GStars' tracked GitHub repository data over MCP: a public, read-only Streamable HTTP server with no account or API key."
last_updated: 2026-11-19
canonical: "https://www.gstars.dev/mcp"
---

# GStars MCP server

Connect AI agents to GStars' tracked GitHub repository data over MCP: a public, read-only Streamable HTTP server with no account or API key.

## What it is

The GStars MCP server gives AI agents the same data as the [GStars API](https://www.gstars.dev/developers): repositories tracked by GStars, their total stars, measured 7- and 30-day growth, weekly rank, health score and stored star history. It runs at `https://www.gstars.dev/api/mcp` over the Streamable HTTP transport. It is stateless and read-only, needs no account, session or API key, and only reads the stored dataset: no tool calls GitHub on demand or changes anything.

## Tools

Each tool maps to one public API operation and takes the same parameters.

- `search_repos` (Search and rank repositories): Find tracked repositories by text, category/topic and language. Most popular means total stars. Stable server-side sorting happens before pagination. Parameters: `q`, `category`, `language`, `sort`, `limit`, `offset`.
- `get_repo` (Repository snapshot): Read one stored repository, its latest measured growth and health. Optional history uses stored star snapshots; it never calls GitHub. Check as\_of and last\_synced\_at before citing counts. Parameters: `owner`, `name`, `include_history`.
- `get_trending` (Trending repositories): Ranked recent star growth in the latest measured ranking week. window=30d returns 30-day growth and rank. Returned ranks are site-wide, even when filtering by category/topic. Parameters: `window`, `category`, `limit`, `offset`.
- `list_categories` (Category and topic directory): Discover populated categories and GitHub topics, repository counts and canonical /c/ URLs. An unbounded request retains the complete catalog for compatibility; use limit/offset for tool calls. Parameters: `q`, `limit`, `offset`.

A second, documentation server at `https://www.gstars.dev/api/mcp/docs` lets an agent list, search and read GStars’ own documentation pages, such as the methodology, the API documentation and this page.

## Connect a client

Claude Code (both servers):

```bash
claude mcp add --transport http gstars https://www.gstars.dev/api/mcp
claude mcp add --transport http gstars-docs https://www.gstars.dev/api/mcp/docs
```

Any client that reads an `.mcp.json` file:

```json
{
  "mcpServers": {
    "gstars": {
      "type": "http",
      "url": "https://www.gstars.dev/api/mcp"
    },
    "gstars-docs": {
      "type": "http",
      "url": "https://www.gstars.dev/api/mcp/docs"
    }
  }
}
```

The machine-readable server card is at [/.well-known/mcp/server-card.json](https://www.gstars.dev/.well-known/mcp/server-card.json).

## Limits and fair use

No API key is required. Cache GET results for one hour, bound concurrency, and honor Retry-After on 429/503 with exponential backoff. MCP POST calls reuse a bounded per-instance cache but are not CDN-cacheable. No global rate-limit guarantee is advertised.

Results cover repositories tracked by GStars, not all of GitHub, and growth that could not be measured is returned as null, not zero. See the [methodology](https://www.gstars.dev/methodology) for how each number is computed.

## More for developers

- [GStars API documentation](https://www.gstars.dev/developers), including the versioning and deprecation policy.
- [OpenAPI schema](https://www.gstars.dev/openapi.json) for the same operations as JSON endpoints.
- [Repository evaluation skill](https://www.gstars.dev/skills/gstars-repo-evaluation/SKILL.md) with a step-by-step workflow for agents.
- [Agent guide](https://www.gstars.dev/agents.md) in Markdown.

## Sitemap

- [Sitemap](https://www.gstars.dev/sitemap.md)
- [llms.txt](https://www.gstars.dev/llms.txt)
