Publish your MCP Server on GitHub with a professional README, license, and installation documentation.
Before publishing on GitHub, your repository needs to be clean and organized. This means initializing Git and configuring a .gitignore suitable for Python and ensure that sensitive or unnecessary files are never committed. A well-prepared repository conveys professionalism and makes contributions easier.
Essential steps to prepare the repository:
# Inicializar o repositório $ git init # Criar .gitignore com template Python $ curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore # Primeiro commit $ git add . $ git commit -m "Initial commit: MCP Server structure"
O .gitignore for Python should exclude: __pycache__/, .env, .venv/, dist/, *.egg-info/ and other build artifacts.
.env — API keys and secrets__pycache__/ — Python cache.venv/ — local virtual environmentdist/ — build artifactspyproject.toml — package definitionuv.lock — dependency lockfilesrc/ — server source code.gitignore — exclusion rules
Use the official Python .gitignore template from GitHub—it covers more than 30 file patterns that shouldn’t be committed. If you’ve already committed a .env if you accidentally do this, remove it from the history with git filter-branch or BFG Repo-Cleaner and immediately replace all exposed keys.
The README is the entry point for your project. It’s the first thing anyone sees when they visit your GitHub repository. A well-written README can make the difference between someone installing and using your server or closing the tab in 5 seconds. It should clearly explain what the server does, how to install it, and how to configure it.
A professional README for an MCP Server should contain these essential sections: title and description clear about what the server does; installation with exact commands to install via uv or pip; configuration in Claude Desktop with the exact JSON for the claude_desktop_config.json; available tools with a description of each tool; and usage examples showing real interactions. Python and License badges at the top add visual credibility.
Project name, one-line description, and badges (Python version, License, Build status).
Clear commands: uv pip install git+https://github.com/usuario/repo or clone + install locally.
Exact JSON to add to claude_desktop_config.json, with the required environment variables.
List of all tools with descriptions and example prompts the user can use in Claude.
Use the 30-second test: if someone can't understand what your server does and how to install it in 30 seconds by reading the README, it needs to be rewritten. Put the installation command and Claude Desktop configuration right at the beginning — those are the most frequently sought-after details.
A project without a license is, by default, all rights reserved — no one can legally use, modify, or distribute your code. Adding an open source license is essential so the community can contribute to and use your MCP Server. In addition, contribution guidelines help maintain the project's quality.
A MIT License is the most popular choice for open source projects—it’s simple, permissive, and allows commercial use. Just create a file LICENSE in the project root with the standard MIT text. For contributions, a CONTRIBUTING.md should explain how to report bugs, suggest features, and submit pull requests. Optionally, a CODE_OF_CONDUCT.md establishes rules for the community to coexist.
The MIT License is used in more than 44% of open-source projects on GitHub, followed by Apache 2.0 (18%) and GPL 3.0 (9%). Projects with clear licenses receive 3x more contributions than projects without a license. Most community-published MCP Servers use MIT—it’s the de facto standard for this ecosystem.
GitHub Actions lets you automate tests and checks on every push or pull request. For an MCP Server, a basic CI (Continuous Integration) workflow ensures that the code passes the linter, the package builds without errors, and imports work correctly. This prevents broken code from reaching the main branch.
A simple YAML workflow for MCP Server CI:
name: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v4 - run: uv sync - run: uv run ruff check . - run: uv build - run: uv run python -c "import meu_server"
This workflow installs dependencies, runs the linter ruff, tests the build, and verifies that the package can be imported. Save it to .github/workflows/ci.yml.
Use astral-sh/setup-uv to configure the uv in GitHub Actions—it’s the fastest way to install Python dependencies in CI. The ruff is the fastest linter in the Python ecosystem and covers the same rules as flake8, isort, and pyupgrade in a single binary.
Never put secrets directly in the workflow YAML. If your MCP Server needs API keys for testing, use GitHub Secrets (Settings → Secrets → Actions) and reference them as ${{ secrets.API_KEY }} in the workflow. Hardcoded secrets in workflows are visible to anyone with access to the repository.
Tags and releases are the professional way to mark stable versions for your project. A Git tag marks a specific point in the history; a GitHub Release combines that tag with changelog notes, allowing users to identify and install specific versions of your MCP Server.
The release creation flow:
# Atualizar versão no pyproject.toml para 0.1.0 # Commitar a mudança $ git add pyproject.toml $ git commit -m "Release v0.1.0" # Criar tag anotada $ git tag -a v0.1.0 -m "First stable release" # Push com tags $ git push origin main --tags
Use semver (semantic versioning): v0.1.0 for the first release, incrementing PATCH for fixes, MINOR for features, and MAJOR for breaking changes. On GitHub, create a Release from the tag with a changelog describing what changed.
Update the version in the pyproject.toml and commit the change.
Create an annotated tag with git tag -a and push to the remote with --tags.
On GitHub, create a Release from the tag with a changelog describing bug fixes, features added, and breaking changes.
Keep a consistent changelog format across releases. Use categories like "Added", "Fixed", "Changed" e "Breaking" so users can quickly see what changed. The format Keep a Changelog is an excellent reference.
The final test before announcing your MCP Server is the clean clone test: clone the repository into a different folder (or onto another machine), follow the README instructions exactly, and verify that everything works. If you can't install it by following your own README, no one else will be able to either.
The installation test simulates the experience of a new user:
# Clonar em pasta limpa $ git clone https://github.com/usuario/meu-mcp-server /tmp/teste $ cd /tmp/teste # Seguir instruções do README $ uv sync $ uv run meu-server # Verificar que funciona no Claude Desktop # Configurar e testar uma chamada de tool
If any step fails, update the README or fix the issue before publishing. The test should cover: installation, execution, configuration in Claude Desktop, and at least one working tool call.
Clone the repository into a temporary folder and check that the structure is complete.
Install by following the README exactly — no extra steps that "you know" but didn’t document.
Run the server, configure it in Claude Desktop, and successfully execute at least one tool.
Next Module: 5.3 — HTTP/SSE Transport