GitHubCard

GitHubCard MCP server

Let your AI assistant create GitHubCard images: profile and repository cards for READMEs, link previews and social posts, with live GitHub data.

• Hosted: https://githubcard.com/mcp (Streamable HTTP). Nothing to install.
• Local: npx -y @ghcardhq/ghcard mcp (stdio), from the ghcard CLI. It can also edit a README on your disk.

Ask things like:

Make a GitHubCard for my profile and add it to the top of my README.

Create a dark card for vercel/next.js I can use as a link preview.

Use the compact repo template, but with a #1e3a5f background and without the language widget.

Get an API key

Creating cards needs a free API key. Sign in at githubcard.com/dashboard and create one under API keys. It looks like ghc_live_….

Without a key, the server still lists templates, palettes and widget types, so you can try it before signing up.

Setup

Replace ghc_live_… with your key in the examples below.

Claude Code

claude mcp add --transport http githubcard https://githubcard.com/mcp \
  --header "Authorization: Bearer ghc_live_…"

There is also a Claude Code plugin that adds the server together with a GitHubCard skill: see ghcardhq/skills.

Claude Desktop

Settings → Connectors → Add custom connector, URL https://githubcard.com/mcp. Custom headers are not available there yet, so to pass your key, use the local server in claude_desktop_config.json instead:

{
  "mcpServers": {
    "githubcard": {
      "command": "npx",
      "args": ["-y", "@ghcardhq/ghcard", "mcp"],
      "env": { "GHCARD_API_KEY": "ghc_live_…" }
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "githubcard": {
      "url": "https://githubcard.com/mcp",
      "headers": { "Authorization": "Bearer ghc_live_…" }
    }
  }
}

VS Code

.vscode/mcp.json (VS Code asks for the key once and stores it securely):

{
  "inputs": [
    {
      "id": "githubcard-key",
      "type": "promptString",
      "description": "GitHubCard API key",
      "password": true
    }
  ],
  "servers": {
    "githubcard": {
      "type": "http",
      "url": "https://githubcard.com/mcp",
      "headers": { "Authorization": "Bearer ${input:githubcard-key}" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "githubcard": {
      "serverUrl": "https://githubcard.com/mcp",
      "headers": { "Authorization": "Bearer ghc_live_…" }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.githubcard]
url = "https://githubcard.com/mcp"
bearer_token_env_var = "GHCARD_API_KEY"

Then export GHCARD_API_KEY=ghc_live_… in your shell.

Any other client

Remote: Streamable HTTP at https://githubcard.com/mcp, header Authorization: Bearer ghc_live_….

Local (stdio): command npx, args ["-y", "@ghcardhq/ghcard", "mcp"], env GHCARD_API_KEY. Add --allow-file-writes to the args to enable update_readme. Needs Node.js 20 or later.

Tools

Tool	Key	What it does
create_card	yes	Create (or reuse) a card for a user or owner/repo. Returns SVG/PNG links and Markdown/HTML embed snippets. Uses one unit of the daily quota
validate_card	yes	Dry run of create_card: checks ids, Pro features and custom designs, uses no quota
list_templates	no	Layouts, filterable by scope (profile/repo), Free plan and widget types
list_palettes	no	Background palettes
list_components	no	Widget types a card can contain
get_template_design	no	A template's layout as an editable design document
get_card_design	yes	The design document of one of your cards
list_cards	yes	Cards you have created
delete_card	yes	Delete a card; its links stop working
get_usage	yes	Your plan and today's remaining quota
update_readme	local only	Insert or update the card in a Markdown file. Only with ghcard mcp --allow-file-writes

create_card is idempotent: the same inputs return the same card and link. Card images always show current GitHub data, so there is no need to recreate them.

Failed calls return isError: true with a stable code, a retryable flag and a hint telling the model what to do next.

Limits

Plan	Cards per day
Free	100
Pro	5000

The quota resets at 00:00 UTC. Failed calls are not counted. Free cards carry a small watermark. See pricing.

Links

• githubcard.com: the editor and gallery
• ghcardhq/ghcard: the CLI and local MCP server
• ghcardhq/skills: Claude Code plugin and skill
• server.json: the entry in the MCP registry, as com.githubcard/mcp

License

MIT