RepoCard
Designs and renders 1280×640 social preview cards for GitHub repositories by reading repo metadata, README, topics and languages through the GitHub API. Provides tools to create a card for a single repo (returning the PNG inline, a stable URL, the design spec and setup steps), list card and settings URLs for every public repo of a user or organization, fetch four art-directed design concepts with rationale, and get step-by-step instructions for setting a repo's social preview. Supports bulk export, a CLI that uploads cards through GitHub's settings UI, and a GitHub Action that regenerates and commits the preview image (optionally as a README banner).
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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=paperFrom 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
Open your repository's Settings (you need admin access).
Under Social preview, click Edit → Upload an image…
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 | |
Cards for every public repo of a user or org, one-click settings links, ZIP download with an index of links. | |
| Uploads each card through your own logged-in browser (Playwright). Dry run by default, keeps existing custom previews unless |
GitHub Action | Regenerates |
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 cardYou 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: trueInputs: 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 |
| Design and render a card. Returns the PNG inline, a stable URL, the design and setup steps. |
| The four concepts with rationale and URLs ( |
| Card and settings URLs for every public repo of an account. |
| Step-by-step instructions and automation options. |
| The full design vocabulary. |
Plain HTTP agents can use /llms.txt and /openapi.json.
HTTP API
Endpoint | Returns |
| PNG. Errors return a PNG explaining the problem, with the matching status. |
| SVG. |
| Four concepts with specs, PNG/SVG URLs, Markdown, HTML and setup steps. |
| Same, from |
| Public repos with card and settings URLs ( |
| All layouts, palettes, fonts, backgrounds and parameters. |
| 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
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 deployBefore 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 |
| binding | Workers AI. Remove for deterministic designs only. |
| KV binding | Stores designs so each repo keeps a stable look. |
| rate limit bindings | Per-IP limits for new renders (60/min) and AI generations (10/min). |
| secret | 5,000 instead of 60 GitHub API requests/hour. Strongly recommended. |
| var |
|
| var | Default |
| var / secret | Any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, Together, Ollama). |
| 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 palettessrc/
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 suitesSee 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Create GitHub profile and repository cards for READMEs, link previews and social posts.
Give agents instant OG image generation, social metadata audits, and rendering guidance.
Social cards and OG images from designed templates: card from a URL, presets, meta tags, link checks
Render Open Graph and social images from HTML templates, build og:image URLs, AI templates.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.318 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceCreate GitHub profile and repository cards for READMEs, link previews and social posts.105 npm2MIT