---
name: gitbanners
description: Create live GitHub profile, organization and repository banner images with GitBanners and embed them in a README or a web page. Use when asked to add a GitHub stats banner, contribution graph or contributor wall to a README, to generate an embeddable SVG or PNG for a GitHub user or repository, to pick a banner theme or size, or to look up the GitBanners URL patterns, JSON API or MCP tools.
---

# GitBanners

GitBanners draws live GitHub banners as SVG or PNG from a URL. Everything below is public, read-only and free. No API key and no sign-in are needed.

## Embed a banner

```md
[![GitHub banner](https://gitbanners.com/OWNER.svg)](https://gitbanners.com/OWNER)
```

Replace `OWNER` with a GitHub login. For a repository use `OWNER/REPO`:

```md
[![GitHub banner](https://gitbanners.com/OWNER/REPO.svg)](https://gitbanners.com/OWNER/REPO)
```

## Choose what it shows

- A preset is the last path segment: `https://gitbanners.com/OWNER/streak.svg`, `https://gitbanners.com/OWNER/REPO/contributors.svg`.
- Options are query parameters: `?theme=dracula`, `?size=og`, `?accent=ff7ac6`.
- `.png` instead of `.svg` for surfaces that do not draw SVG. `?size=` takes `x`, `linkedin`, `og`, `social`, `square` for fixed upload sizes.
- Every preset, theme, size and parameter: `GET https://gitbanners.com/api/v1/options`.

## Check before you embed

Ask the API. It confirms the target exists and returns the exact URLs and snippets:

```sh
curl "https://gitbanners.com/api/v1/banner?target=OWNER/REPO&preset=contributors"
```

A banner image URL answers 200 also for a login that does not exist (the image then says so), which is why the check belongs in the API call.

## Machine interfaces

- JSON API: https://gitbanners.com/api/v1 (OpenAPI: https://gitbanners.com/openapi.json)
- MCP server, Streamable HTTP: https://gitbanners.com/mcp (tools: get_banner, search_github, get_owner, get_repository, list_banner_options)
- Docs: https://gitbanners.com/docs (Markdown: https://gitbanners.com/docs.md)
- Any page as Markdown: add `.md` or send `Accept: text/markdown`

## Errors and limits

Failures are RFC 9457 `application/problem+json` with a stable `code` and a `resolution` hint. Responses carry `RateLimit-Policy` and `RateLimit`. On 429 wait for `Retry-After` seconds.