Badge

A GitHub Action that turns a live MCP (Model Context Protocol) conformance check into a self-contained SVG badge for your README — no badge service, no third-party host, no account. It runs the check, writes an .svg, and you commit it. The badge above is this repo's own, refreshed on a schedule against a real endpoint.

License: MIT

🌐 English · 🇻🇳 Tiếng Việt

---

Build badges tell people your code compiles. An MCP badge tells people your server actually speaks the protocol — the initialize handshake works, tools/list returns valid schemas, ping responds, errors follow JSON-RPC. This action generates that badge as a plain SVG committed to your repo, so it renders anywhere GitHub renders images and depends on nothing external. It wraps the mcp-conformance CLI.

Quick start

Add a workflow that regenerates the badge on a schedule and commits it:

name: MCP Badge
on:
  schedule:
    - cron: "0 */6 * * *"   # every 6 hours
  workflow_dispatch:

permissions:
  contents: write

jobs:
  badge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tuanone123/mcp-badge@v1
        with:
          url: https://your-server.example.com/api/mcp
          output: assets/mcp-badge.svg
      - name: Commit badge if changed
        run: |
          if ! git diff --quiet -- assets/mcp-badge.svg; then
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add assets/mcp-badge.svg
            git commit -m "chore: refresh MCP badge"
            git push
          fi

Then embed it in your README:

![MCP](./assets/mcp-badge.svg)

Inputs

Input	Required	Default	Description
url	yes	—	The MCP server's Streamable-HTTP endpoint.
header	no	""	Extra HTTP header(s), one per line, in Key: Value form (e.g. auth tokens).
label	no	MCP	Left-hand label text on the badge.
output	no	mcp-badge.svg	Path to write the SVG to.
fail-on-error	no	false	Also fail the job when the server is not conformant (the badge is still written).
ref	no	default branch	Git ref of mcp-conformance to run.

Outputs

Output	Description
status	passing or failing.
passed	Number of checks that passed.
failed	Number of checks that failed.

Badge states

Looks like	When
MCP · passing (green)	Every conformance check passed.
MCP · N failing (red)	One or more checks failed.
MCP · unreachable (grey)	The endpoint couldn't be reached or didn't return JSON.

How it works

This is a composite action. It runs npx -y github:tuanone123/mcp-conformance <url> --json, parses the summary, and writes a flat SVG (rendered by a tiny bundled Node script — no shields.io call, no runtime dependencies). Because the badge is a committed file, it works on private repos and offline mirrors too.

Want the check to gate CI instead of drawing a badge? Use mcp-conformance-action.

Related

• mcp-conformance — the CLI this action wraps.
• mcp-conformance-action — fail your CI build on any MCP regression.
• awesome-mcp-testing — curated tools to test, evaluate and validate MCP servers.
• Model Context Protocol — the official protocol site and docs.

License

MIT © tuanone123