Skip to main content
Glama

The social preview is the image people see when your repository link is shared on X, LinkedIn, Slack, Discord or iMessage. Most repos show GitHub's generic card, and template generators put every project on the same layout. RepoCard designs a card that fits your project instead.

  • Designed, not templated. An LLM reads the description, README, topics and languages, then art-directs four distinct concepts: layout, palette, typography, a one-line tagline and keywords.

  • Crisp, correct text. The model never draws pixels. Code renders the design with real fonts, so there's no garbled AI lettering. Output is exactly 1280×640 and under GitHub's 1 MB limit.

  • Always legible. Sixteen curated palettes that pass WCAG contrast, and brand accents adjusted until they're readable.

  • Every repo, not just one. Bulk export for a whole account, a CLI that can upload to every repo, and a GitHub Action that keeps cards fresh.

  • Agent-native. MCP server, OpenAPI spec and llms.txt, so AI agents can design and explain setup for you.

  • Runs on Cloudflare. One Worker with Workers AI, KV and static assets. MIT licensed and self-hostable.

Why RepoCard

GitHub default

Template generators

RepoCard

Design fits the project

No

Same layout for every repo

Yes, art-directed from your README

Choices per repo

1

1 template

4 concepts + fine-tuning

Tagline

Raw description

Raw description

Written for the card

Contrast and legibility checks

n/a

No

WCAG-checked palettes

Whole account at once

No

No

Bulk export, CLI upload, Action

AI agents

No

No

MCP server, OpenAPI, llms.txt

Self-hostable

No

Varies

Yes, one Cloudflare Worker (MIT)

Use cases: launching a project on Hacker News, X or Product Hunt; giving an organization's repos a consistent look; README header banners; letting your coding agent ship a preview with every new repo.

Related MCP server: ogstamp

Quick start

On the web: open repocard.xyz, paste a repository link, pick a concept, and click Download PNG.

As a URL (embed anywhere):

https://repocard.xyz/card/OWNER/REPO.png
https://repocard.xyz/card/OWNER/REPO.png?variant=2&palette=paper

From the terminal:

npx repocard card vercel/next.js          # one card
npx repocard bulk your-username           # every public repo of an account
npx repocard apply your-username --yes    # upload them all (see below)

Add it to GitHub

  1. Open your repository's Settings (you need admin access).

  2. Under Social preview, click Edit → Upload an image…

  3. Choose the PNG. Done.

GitHub has no public API for the social preview: it can be read (openGraphImageUrl in GraphQL) but not set. That's why RepoCard offers three ways to cover many repositories:

What it does

Bulk export

Cards for every public repo of a user or org, one-click settings links, ZIP download with an index of links.

repocard apply

Uploads each card through your own logged-in browser (Playwright). Dry run by default, keeps existing custom previews unless --overwrite, and verifies each upload through the API.

GitHub Action

Regenerates .github/social-preview.png on a schedule and can keep it as a README banner.

Automatic upload with the CLI

npm install -g playwright && npx playwright install chromium   # once

npx repocard apply your-username          # dry run: renders cards, shows the plan
npx repocard apply your-username --yes    # opens a browser; sign in; it uploads each card

You sign in to GitHub yourself in the browser window, and RepoCard never sees your password or cookies. With a token (GITHUB_TOKEN, GH_TOKEN or gh auth login), it skips repos where you aren't an admin and confirms each upload took effect. It drives GitHub's web UI, so a settings-page redesign can break it; failures print the settings link and PNG path so you can finish by hand.

GitHub Action

# .github/workflows/social-preview.yml
name: Social preview
on:
  workflow_dispatch:
  schedule:
    - cron: '0 6 * * 1'
permissions:
  contents: write
jobs:
  card:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nirholas/RepoCard@v1
        with:
          readme-banner: true

Inputs: variant, layout, palette, font, path (default .github/social-preview.png), readme-banner, readme-path, commit, commit-message, endpoint. See action.yml.

For AI agents

RepoCard is an MCP server (Streamable HTTP, no auth):

claude mcp add --transport http repocard https://repocard.xyz/mcp
// Cursor (.cursor/mcp.json)
{ "mcpServers": { "repocard": { "url": "https://repocard.xyz/mcp" } } }
// VS Code (.vscode/mcp.json)
{ "servers": { "repocard": { "type": "http", "url": "https://repocard.xyz/mcp" } } }

Tool

Purpose

create_social_preview

Design and render a card. Returns the PNG inline, a stable URL, the design and setup steps.

get_design_concepts

The four concepts with rationale and URLs (refresh for new ones).

list_account_cards

Card and settings URLs for every public repo of an account.

how_to_set_social_preview

Step-by-step instructions and automation options.

get_design_options

The full design vocabulary.

Plain HTTP agents can use /llms.txt and /openapi.json.

HTTP API

Endpoint

Returns

GET /card/{owner}/{repo}.png

PNG. Errors return a PNG explaining the problem, with the matching status.

GET /card/{owner}/{repo}.svg

SVG.

GET /api/v1/cards/{owner}/{repo}

Four concepts with specs, PNG/SVG URLs, Markdown, HTML and setup steps.

POST /api/v1/cards

Same, from {"repo": "<any GitHub URL>", "refresh": true}.

GET /api/v1/users/{owner}/repos

Public repos with card and settings URLs (?forks=1&archived=1&limit=300).

GET /api/v1/options

All layouts, palettes, fonts, backgrounds and parameters.

POST /mcp

MCP endpoint.

Card parameters: variant (1-4), layout, palette, font, background, mark, emoji, accent, title, tagline, chips, stats=0, owner=0, mode=fast. Full reference in the docs.

How it works

flowchart LR
  A[Repository link] --> B[GitHub API<br/>metadata · README · languages]
  B --> C{Stored design?}
  C -- yes --> E
  C -- no --> D[LLM art director<br/>4 concepts from a closed vocabulary]
  D -->|invalid, slow or unavailable| F[Deterministic fallback]
  D --> V[Validate · clamp text · enforce contrast]
  F --> V
  V --> K[(KV)] --> E[Satori layout → native SVG backgrounds → resvg PNG]
  E --> G[Edge cache → 1280×640 PNG]
  • The README is passed to the model as untrusted data. The model only chooses from enums plus short text, which is cleaned and length-limited before rendering.

  • Designs are stored per repository, so a card's look is stable; stats refresh every few hours.

  • Backgrounds are drawn as native SVG rather than CSS gradients, which rasterizes about 4-5× faster. A typical render takes ~50-300 ms of CPU.

Self-hosting

Deploy to Cloudflare

git clone https://github.com/nirholas/RepoCard && cd RepoCard
npm install
npx wrangler login
npx wrangler secret put GITHUB_TOKEN    # fine-grained, public repositories, read-only
npm run deploy                          # KV and rate limiters are provisioned on first deploy

Before deploying your own copy, edit wrangler.jsonc: replace the repocard.xyz entries in routes with your domain (or remove routes and set "workers_dev": true), and set PUBLIC_URL to match.

Plan requirement: new renders need more than the Free plan's 10 ms of CPU per request, so use the Workers Paid plan. Use a custom domain in production: the Workers Cache API, which caches rendered images at the edge, isn't available on *.workers.dev.

Setting

Kind

Purpose

AI

binding

Workers AI. Remove for deterministic designs only.

DESIGNS

KV binding

Stores designs so each repo keeps a stable look.

RENDER_LIMITER, AI_LIMITER

rate limit bindings

Per-IP limits for new renders (60/min) and AI generations (10/min).

GITHUB_TOKEN

secret

5,000 instead of 60 GitHub API requests/hour. Strongly recommended.

AI_PROVIDER

var

workers-ai (default), openai-compatible, or none.

AI_MODEL

var

Default @cf/meta/llama-3.3-70b-instruct-fp8-fast.

LLM_BASE_URL, LLM_MODEL, LLM_API_KEY

var / secret

Any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, Together, Ollama).

PUBLIC_URL

var

Canonical origin for returned URLs.

Development

npm install
npm run dev                                   # local Worker at http://localhost:8787
npm test                                      # unit, API, MCP and real rendering tests
npm run typecheck
npm run preview -- vercel/next.js             # render cards to ./preview with Node
npm run preview -- --matrix nirholas/three.ws # every layout × sample palettes
src/
  design/     vocabulary, palettes, contrast, AI designer, deterministic fallback
  render/     Satori layouts, native SVG backgrounds, fonts, render engine
  lib/        repo link parsing, GitHub client, HTTP helpers
  app.ts      routes · service.ts caching and designs · mcp.ts MCP server
public/       website (generator, bulk export, docs)
packages/cli/ the `repocard` npm package
action.yml    the GitHub Action
test/         Vitest suites

See CONTRIBUTING.md, CODE_OF_CONDUCT.md and SUPPORT.md. Report vulnerabilities privately per SECURITY.md. Coding agents: start with AGENTS.md and llms.txt.

FAQ

Does it work with private repos? No. It reads public data through the GitHub API and never asks for account access.

Which model designs the cards? An open model on Cloudflare Workers AI by default; any OpenAI-compatible endpoint when self-hosting. If the model fails, RepoCard falls back to deterministic designs, so you always get a card.

Why does X/LinkedIn still show the old image? Platforms cache link previews for days. Most have a tool to refresh a URL.

Star and share

If RepoCard helped, a ⭐ on GitHub means a lot. Share it: X · LinkedIn · Reddit · Hacker News

License

MIT. Fonts are bundled under the SIL Open Font License (notices); emoji are Twemoji (CC-BY 4.0). RepoCard is not affiliated with GitHub.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents like Claude Code and ChatGPT to build GitHub profile SVG cards using ProfileKit's 28 card types and 17 themes via natural language.
      3
      18 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to render 1200×630 Open Graph social card images from a title, subtitle, and theme, returning a public PNG URL. It also provides pricing information for purchasing one-time forever credits.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to render 1200x630 Open Graph social preview images from templates and receive back a cacheable PNG URL. Exposes a create_og_image tool over a remote Streamable HTTP endpoint.
      MIT