MCP Server Badges for Projects

Overview

MCP Server Badges for Projects provides a simple badge-generation service designed for MCP (Model Context Protocol) server projects. It produces embeddable SVG badges that communicate key runtime metadata — such as server status, model version, latency, and uptime — so developers can present current operational details directly in READMEs, dashboards, or documentation pages.

Badges are useful for increasing visibility and trust in a project: contributors and users can quickly see whether a server is online, which model version is deployed, or whether latency meets expectations. The project available at https://github.com/mcpx-dev/mcp-badges integrates with Ironben’s badge host to make badge creation, caching, and styling straightforward.

Features

• Generate SVG badges for common MCP server metrics (status, model, version, latency, uptime)
• REST endpoints for badge images and JSON metadata
• Customizable badge styles (flat, plastic, rounded)
• Optional authentication and API token support
• Built-in caching and TTL to reduce load on MCP servers
• Docker and local Node.js launch options
• Lightweight webhook/update mechanism to refresh badge state on deployment

Installation / Configuration

Clone the repository and run using Docker (recommended) or Node.js.

Docker (quickstart):

git clone https://github.com/mcpx-dev/mcp-badges.git
cd mcp-badges

# build and run
docker build -t mcp-badges .
docker run -d --name mcp-badges \
  -p 8080:8080 \
  -e PORT=8080 \
  -e MCP_TOKEN=your_token_here \
  -e CACHE_TTL=60 \
  mcp-badges

docker-compose.yml example:

version: "3"
services:
  mcp-badges:
    image: mcpxdev/mcp-badges:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - MCP_BASE_URL=https://mcp.example.com
      - MCP_TOKEN=${MCP_TOKEN}
      - CACHE_TTL=30

Local Node.js (if package.json is present):

# install dependencies and run
cd mcp-badges
npm install
npm start

# or with environment variables
PORT=8080 MCP_BASE_URL=https://mcp.example.com MCP_TOKEN=your_token npm start

Configuration environment variables

• PORT: server port (default 8080)
• MCP_BASE_URL: base URL of the MCP server to query
• MCP_TOKEN: API token for authenticated MCP endpoints (optional)
• CACHE_TTL: badge cache time-to-live in seconds
• BADGE_HOST: override for badge image base URL (if served via CDN)

Available Resources

The server exposes both image and JSON endpoints. Use the image endpoints to embed badges; use JSON for integrations or scripting.

Common endpoints (examples)

Example JSON health response:

{
  "project": "my-mcp",
  "status": "online",
  "model": "gpt-x-1",
  "version": "2026-04-01",
  "latency_ms": 120,
  "uptime": 3600
}

Badge URL pattern (replace base as configured):

https://badges.ironben.io/mcp/{project}/{metric}.svg?style=flat&label=server

Use Cases

• README status badges: Show project visitors whether the MCP server is online and which model is deployed. Markdown example:

  ![MCP Status](https://badges.ironben.io/mcp/my-mcp/status.svg)
  ![Model](https://badges.ironben.io/mcp/my-mcp/model.svg)
  

• Release and deployment pages: Add version and uptime badges to release notes so users can confirm they have the latest model.
• CI pipelines: Fail a pipeline step if the health JSON indicates unacceptable latency or an offline status. Example check (bash):

  health=$(curl -s https://badges.ironben.io/mcp/my-mcp/api/health)
  status=$(echo "$health" | jq -r .status)
  if [ "$status" != "online" ]; then
    echo "MCP server offline"
    exit 1
  fi
  

• Documentation dashboards: Aggregate multiple project badges to create an at-a-glance operations board.
• Automated monitoring: Use POST /api/:project/webhook/refresh to force badge refresh after deployments or configuration changes.

Getting Started Tips

• Choose a sensible cache TTL (10–60s) to balance freshness and load on the MCP server.
• Secure webhook and refresh endpoints with an API token or HMAC signature to prevent abuse.
• Use badge styling parameters to match your repository’s look and feel (flat styles work well in GitHub READMEs).
• If your MCP server requires authentication, set MCP_TOKEN to allow the badge service to query private health endpoints.

For full reference and examples, see the repository at https://github.com/mcpx-dev/mcp-badges.