How to Contribute to Awesome MCP Servers: A Complete Guide

Contributing to Awesome MCP Servers requires forking the repository, adding your server entry to README.md with a valid Glama badge and category emoji, and submitting a pull request that passes automated validation checks in .github/workflows/check-glama.yml.

The Awesome MCP Servers repository is the definitive curated list of Model Context Protocol (MCP) server implementations. Maintained by punkpeye/awesome-mcp-servers, this community-driven index relies on a structured contribution workflow enforced by automated GitHub Actions to ensure every entry remains discoverable, properly categorized, and verified.

Understanding the Contribution Requirements

Before submitting code, review the guidelines in CONTRIBUTING.md and README.md. Every entry must include specific formatting elements validated by the check-glama.yml workflow to maintain consistency across the list.

Required Entry Components

Each server entry must contain three mandatory elements:

• An emoji tag representing the primary language or deployment type (e.g., 🐍 Python, 🏎️ Go, ☁️ Cloud)
• A markdown link using the full owner/repo format (not just the repository name)
• A Glama badge linking to the server's score page on glama.ai

The workflow validates against a whitelist of permitted emojis: 🎖️ (official), 🐍 (Python), 📇 (TypeScript/JS), 🏎️ (Go), 🦀 (Rust), #️⃣ (C#), ☕ (Java), 🌊 (C/C++), 💎 (Ruby), ☁️ (Cloud), 🏠 (Local), 📟 (Embedded), 🍎 (macOS), 🪟 (Windows), and 🐧 (Linux).

Step-by-Step Contribution Process

1. Fork and Clone the Repository

Create a personal fork of punkpeye/awesome-mcp-servers and clone it locally. Create a descriptive feature branch such as add-new-server:

git clone https://github.com/YOUR_USER/awesome-mcp-servers.git
cd awesome-mcp-servers
git checkout -b add-new-server

2. Add Your Server Entry to README.md

Edit README.md to insert your server under the appropriate category. The entry must follow this exact format:

📇 🐍 ☁️ - [owner/repo](https://github.com/owner/repo) - Brief description of the MCP server functionality. \
[![owner/repo MCP server](https://glama.ai/mcp/servers/owner/repo/badges/score.svg)](https://glama.ai/mcp/servers/owner/repo)

Replace owner/repo with your actual GitHub organization and repository name. The Glama badge is mandatory and must use the exact SVG path structure glama.ai/mcp/servers/owner/repo/badges/score.svg.

3. Commit and Push Changes

Stage your changes with a clear, descriptive commit message:

git add README.md
git commit -m "Add owner/repo MCP server"
git push origin add-new-server

4. Open a Pull Request

Navigate to the upstream repository and open a PR against the main branch. For automated bot submissions, append 🤖🤖🤖 to the PR title for fast-track processing.

Automated Validation Workflow

Upon creating a pull request, the GitHub Actions workflow defined in .github/workflows/check-glama.yml executes automatically. This workflow performs four critical validations:

• Glama Badge Verification: Confirms the entry contains a valid glama.ai/mcp/servers/.../badges/score.svg image link
• Emoji Validation: Ensures at least one permitted emoji from the whitelist appears in the entry
• Link Format Check: Validates the markdown link uses the full owner/repo naming convention via regex matching
• Duplicate Detection: Scans README.md to verify the server URL does not already exist

If validation fails, the workflow automatically applies labels such as missing-emoji, has-glama, or duplicate, and posts a detailed comment explaining the specific violation.

Required Entry Format Reference

The following template shows the exact syntax required for a Python-based cloud server:

📇 🐍 ☁️ - [exampleorg/example-mcp](https://github.com/exampleorg/example-mcp) A lightweight Python MCP server for file storage. \
[![exampleorg/example-mcp MCP server](https://glama.ai/mcp/servers/exampleorg/example-mcp/badges/score.svg)](https://glama.ai/mcp/servers/exampleorg/example-mcp)

Note the use of a backslash (\) for line continuation and the precise placement of emojis before the link.

Summary

• Contributions follow a standard fork-and-PR workflow defined in CONTRIBUTING.md
• Every entry requires a Glama badge, category emoji, and full owner/repo link format
• The .github/workflows/check-glama.yml workflow enforces quality controls automatically
• Valid entries receive appropriate labels (has-glama, etc.) while invalid submissions get detailed error comments
• Bot-created PRs can use 🤖🤖🤖 in the title for fast-track review

Frequently Asked Questions

What is the Glama badge and why is it required?

The Glama badge displays a quality score for MCP servers hosted on the Glama platform. It is required because it provides users with an immediate visual indicator of server reliability and maintenance status, ensuring the Awesome MCP Servers list maintains high quality standards.

Can I contribute a server that isn't written in a language with a specific emoji?

Yes, choose the emoji that best represents your deployment environment or use a general category like ☁️ for cloud-hosted services. The validator checks against a whitelist including 🐍, 🏎️, 🦀, and others, but you can propose new emojis via an issue if none fit your technology stack.

My PR failed the automated check for duplicate entries but I don't see my server in the list. What happened?

The duplicate validator scans for identical GitHub URLs. If your repository was recently renamed or transferred, the old URL might still exist in README.md. Check the exact URL format in your entry against existing entries, ensuring there are no trailing slashes or protocol differences (http vs https).

How long does it take for a contribution to be merged?

Once the automated checks in .github/workflows/check-glama.yml pass, maintainer review typically occurs within a few days. PRs that include the 🤖🤖🤖 fast-track indicator may be processed more quickly if they meet all automated validation criteria.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}