# How to Contribute to the Awesome MCP Servers Repository: A Step-by-Step Guide

> Learn how to contribute to the awesome-mcp-servers repository. Follow this step-by-step guide to add your MCP server and get it listed. Fork, edit README, and submit your pull request.

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

---

**To contribute to the awesome-mcp-servers repository, fork the project, create a feature branch, edit [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) to add your server entry with the required Glama badge and emoji legend, then submit a pull request for the CI workflow to validate.**

The **awesome-mcp-servers** repository is a curated, markdown-based directory of public Model Context Protocol (MCP) servers maintained by punkpeye. Because the project contains no compiled code and lives entirely in plain markdown files, contributing requires following specific formatting conventions rather than traditional software development patterns.

## Repository Architecture Overview

Understanding the file structure is essential before you contribute to the awesome-mcp-servers repository. The project organizes content across several key locations:

- **[`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md)** – The master document containing categorized server listings, emoji legends, and anchor links for navigation.
- **[`CONTRIBUTING.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md)** – Comprehensive guidelines describing the fork-branch-edit-PR workflow.
- **[`.github/workflows/check-glama.yml`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.github/workflows/check-glama.yml)** – The GitHub Actions CI pipeline that validates markdown formatting and badge URLs.
- **`README-*.md`** – Localized versions (e.g., [`README-zh.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-zh.md), [`README-ja.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-ja.md), [`README-ko.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-ko.md)) providing translations for non-English speakers.

The main [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) uses thematic headings marked with emojis (e.g., `🔗 Aggregators`, `📂 File Systems`). Each heading includes an HTML anchor enabling direct linking, such as `### 🔗 <a name="aggregators"></a>Aggregators` found at line 30 of the README.

## Contribution Workflow

Follow these exact steps when preparing your contribution:

1. **Fork the repository** using the GitHub web interface.

2. **Create a dedicated branch** for your changes:

   ```bash
   git checkout -b add-new-server
   ```

3. **Edit the appropriate README file**, typically [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) for English entries. Insert your server into the correct category section, maintaining alphabetical order within that category.

4. **Commit with a descriptive message**:

   ```bash
   git commit -m "Add <ServerName> – brief description"
   ```

5. **Push to your fork**:

   ```bash
   git push origin add-new-server
   ```

6. **Open a Pull Request** against the upstream `main` branch with a clear title such as "Add MyServer MCP server".

7. **Address CI feedback** – the maintainers will run the validation workflow, and you must resolve any markdown or duplicate entry issues before merging.

## Formatting Requirements for Server Entries

Every server entry in [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) must follow a strict one-line format. Here is the exact syntax used throughout the repository, referencing line 34 for the *Correctover/mcp-server* entry:

```markdown
- [Correctover/mcp-server](https://github.com/Correctover/mcp-server) ![Correctover MCP server](https://glama.ai/mcp/servers/Correctover/mcp-server/badges/score.svg) 📇 ☁️ - One-sentence description under 30 words.

```

**Required components:**

- **Repository link** – Markdown format `[owner/repo](https://github.com/owner/repo)`.
- **Glama badge** – Live score indicator following the pattern `https://glama.ai/mcp/servers/<owner>/<repo>/badges/score.svg`.
- **Category emoji** – Refer to the legend table at lines 44-66 of [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) (e.g., `📇` for TypeScript/JavaScript, `🐍` for Python, `🏎️` for Rust).
- **Scope emojis** – `☁️` for cloud services, `🏠` for local service.
- **Platform emojis** – `🍎` (macOS), `🪟` (Windows), `🐧` (Linux) indicating OS compatibility.

Here is a practical template you can copy and modify:

```markdown
- [myorg/my-mcp-server](https://github.com/myorg/my-mcp-server) ![myorg/my-mcp-server MCP server](https://glama.ai/mcp/servers/myorg/my-mcp-server/badges/score.svg) 📇 ☁️ 🍎 🪟 🐧 - Lightweight MCP server providing cloud-hosted file system access with streaming uploads.

```

## CI Validation and Quality Checks

The repository enforces quality through automated checks defined in [`.github/workflows/check-glama.yml`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.github/workflows/check-glama.yml). This workflow runs on every pull request and performs three critical validations:

1. **Duplicate detection** – Ensures no server appears twice in the listing.
2. **Badge URL resolution** – Verifies all Glama badge URLs return HTTP 200 status.
3. **Alphabetical ordering** – Confirms entries follow alphabetical sequence within their respective categories.

To minimize CI failures, verify your badge URL is reachable before submitting:

```bash
curl -I https://glama.ai/mcp/servers/your-org/your-repo/badges/score.svg

```

A successful contribution passes all three checks without maintainer intervention.

## Contributing Translations

For localized versions, edit the corresponding `README-*.md` file (such as [`README-zh.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-zh.md) for Simplified Chinese or [`README-pt_BR.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-pt_BR.md) for Brazilian Portuguese). These files mirror the structure of the main [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) but require translation of category headings and server descriptions while preserving the technical badge syntax and repository links.

## Summary

- **Fork and branch** before making any edits to [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md).
- **Follow the one-line format**: repository link, Glama badge, emoji legend, and concise description.
- **Use correct emojis** according to the legend table at lines 44-66 (language, scope, and platform indicators).
- **Maintain alphabetical order** within each category section.
- **Verify badge URLs** to ensure the CI workflow in [`check-glama.yml`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/check-glama.yml) passes.
- **Submit a clean PR** against the `main` branch with descriptive commit messages.

## Frequently Asked Questions

### What is the required format for the Glama badge?

The badge must use the exact URL pattern `https://glama.ai/mcp/servers/<owner>/<repo>/badges/score.svg` wrapped in markdown image syntax. For example: `![owner/repo MCP server](https://glama.ai/mcp/servers/owner/repo/badges/score.svg)`. This badge displays the server's live quality score from the Glama registry.

### Can I add a server without a Glama badge?

No. According to the repository standards enforced by the CI workflow in [`.github/workflows/check-glama.yml`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/.github/workflows/check-glama.yml), every server entry must include a valid Glama badge. The workflow validates that badge URLs resolve successfully before allowing merge.

### How do I choose the correct emojis for my server entry?

Consult the legend table located at lines 44-66 of [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md). Select one language emoji (e.g., `📇` for TypeScript, `🐍` for Python), appropriate scope emojis (`☁️` for cloud, `🏠` for local), and all applicable platform emojis (`🍎`, `🪟`, `🐧`). Place these immediately after the badge and before the description text.

### Should I edit the localized README files when adding a new server?

While you may submit changes to localized `README-*.md` files (such as [`README-ja.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-ja.md) or [`README-ko.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-ko.md)), it is not required for the initial PR. Maintainers typically handle synchronization of new entries across language versions, but contributions to translations are welcome if you are fluent in the target language.