# GitHubCard [Verified owner] [Health: Active]

**Category:** 🔄 Version Control  
**Repository:** https://github.com/ghcardhq/githubcard-mcp  
**GitHub Stars:** 15  
**npm Downloads (last month):** 944  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/githubcard

## Description
Create GitHub profile and repository cards for READMEs, link previews and social posts. Hosted at https://githubcard.com/mcp or local via npx @ghcardhq/ghcard mcp.

## Tools
Capabilities this server exposes over MCP:

- **create_card** — Create (or reuse) a published card image for a GitHub profile or repository. Returns svg/png URLs and markdown/html embed snippets. Idempotent; counts once against the daily quota.
- **validate_card** — Dry run of create_card with the same inputs: checks template/palette ids, Pro features and the design document, without creating anything or using quota. warnings lists layers that reach outside the artboard (they would be clipped); fix those before create_card.
- **list_templates** — List card layouts with their ids, scope (profile/repo/all), size, widget types, and whether they need Pro.
- **list_palettes** — List background palette ids accepted by create_card.
- **list_components** — List the widget (layer) types a design can contain: the scope (profile/repo) each fits, the layer settings each reads ("options", e.g. a text layer's style.textAlign or style.backgroundColor), and the font families the renderer embeds ("fonts").
- **get_template_design** — Return a template's layout as an editable design document (artboard + layers). Costs no quota. Edit it and pass it to create_card as design.
- **get_card_design** — Return the design document of one of the account's cards, to edit and re-submit through create_card as design (which creates a new card; the original is unchanged).
- **list_cards** — List cards this account created through the API, most recently requested first. Paginated with nextCursor.
- **delete_card** — Permanently delete one of the account's cards. Its links stop working everywhere they are embedded. Confirm with the user first.
- **get_usage** — Show the account's plan (free/pro) and how many cards it can still create today (cards.remaining, resets 00:00 UTC). The ai quota is reserved for future AI tools.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `GHCARD_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What GitHubCard MCP server does

GitHubCard turns a GitHub username or `owner/repo` identifier into a profile or repository card. Generated cards include links to SVG and PNG images, along with Markdown and HTML snippets for embedding in READMEs, websites, link previews, and social posts. The rendered cards use live GitHub data, so an existing card can reflect updated repository or profile information without being recreated.

The service supports selectable templates, background palettes, widget types, custom backgrounds, and design documents. Repository cards can use options such as compact layouts, while callers can control which visual components appear. A local-only operation can insert or update a card reference in a Markdown README file.

## How it works

The hosted endpoint is available at `https://githubcard.com/mcp` using Streamable HTTP. A local installation runs through `npx -y @ghcardhq/ghcard mcp` and communicates over stdio. Local execution requires Node.js 20 or newer. Add `--allow-file-writes` to the local command when the `update_readme` tool needs to modify files.

Creating or managing cards requires a GitHubCard API key, passed as a bearer token to the hosted service or through `GHCARD_API_KEY` for the local process. Calls that only inspect templates, palettes, and component types can be used without a key. Card creation is idempotent: repeated requests with the same inputs return the same card and link.

## Setup and configuration

Create an API key from the GitHubCard dashboard, then configure it in the MCP client as an authorization header or environment variable. The hosted connection avoids local installation. The local command is useful when an agent must update files on disk, and it can also be used in clients that need environment-based credential configuration.

Claude Code, Cursor, VS Code, Windsurf, Codex CLI, and Claude Desktop each have documented connection patterns. Claude Desktop's custom connector does not provide custom headers, so use the local configuration with `GHCARD_API_KEY` when authentication is required. VS Code can prompt for the key and store it securely.

## Tools and capabilities

- `create_card` creates or reuses a profile or repository card and returns image and embed links. It consumes one unit of the daily quota.
- `validate_card` checks identifiers, Pro-only options, and custom designs without creating a card or using quota.
- `list_templates`, `list_palettes`, and `list_components` expose available layouts, backgrounds, and widget types.
- `get_template_design` returns an editable design document for a template.
- `get_card_design` retrieves the design document for one of the user's cards.
- `list_cards`, `delete_card`, and `get_usage` manage cards and show plan and remaining daily quota.
- `update_readme` inserts or updates a card in a Markdown file and is available only from the local server with file writes enabled.

Failed calls report an error flag, a stable error code, whether retrying is appropriate, and a hint for the next action.

## Limitations and notes

The Free plan allows 100 cards per day and adds a small watermark; the Pro plan allows 5,000. Quotas reset at 00:00 UTC, and failed calls do not count toward the limit. Deleting a card stops its generated links from working. An API key is needed for card creation and account-scoped operations, while catalog tools remain available without one.

_Full upstream README: https://allmcps.com/mcp/githubcard/readme_