# How to Contribute to Awesome MCP Servers: A Complete Guide

> Learn how to contribute to the Awesome MCP Servers repository by forking, adding your server to README.md, and submitting a pull request. Follow our guide for a smooth submission process.

- Repository: [Frank Fiegel/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Contributing to Awesome MCP Servers requires forking the repository, adding your server entry to [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md) and [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md). Every entry must include specific formatting elements validated by the [`check-glama.yml`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`:

```bash
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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) to insert your server under the appropriate category. The entry must follow this exact format:

```markdown
📇 🐍 ☁️ - [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:

```bash
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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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:

```markdown
📇 🐍 ☁️ - [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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md)
- Every entry requires a Glama badge, category emoji, and full `owner/repo` link format
- The [`.github/workflows/check-glama.yml`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.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.