Publique seu MCP Server no GitHub com README profissional, licença e documentação de instalação.
Antes de publicar no GitHub, seu repositório precisa estar limpo e organizado. Isso significa inicializar o Git, configurar um .gitignore adequado para Python e garantir que arquivos sensíveis ou desnecessários nunca sejam commitados. Um repositório bem preparado transmite profissionalismo e facilita contribuições.
Passos essenciais para preparar o repositório:
# 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 para Python deve excluir: __pycache__/, .env, .venv/, dist/, *.egg-info/ e outros artefatos de build.
.env — chaves de API e segredos__pycache__/ — cache do Python.venv/ — ambiente virtual localdist/ — artefatos de buildpyproject.toml — definição do pacoteuv.lock — lockfile de dependênciassrc/ — código-fonte do server.gitignore — regras de exclusão
Use o template oficial de .gitignore para Python do GitHub — ele cobre mais de 30 padrões de arquivos que não devem ser commitados. Se você já commitou um .env por acidente, remova-o do histórico com git filter-branch ou BFG Repo-Cleaner e troque imediatamente todas as chaves expostas.
O README é a porta de entrada do seu projeto. É a primeira coisa que qualquer pessoa vê ao visitar seu repositório no GitHub. Um README bem escrito faz a diferença entre alguém instalar e usar seu server ou fechar a aba em 5 segundos. Ele deve comunicar claramente o que o server faz, como instalar e como configurar.
Um README profissional para um MCP Server deve conter seções essenciais: título e descrição clara do que o server faz; instalação com comandos exatos para instalar via uv ou pip; configuração no Claude Desktop com o JSON exato para o claude_desktop_config.json; tools disponíveis com descrição de cada ferramenta; e exemplos de uso mostrando interações reais. Badges de Python e License no topo adicionam credibilidade visual.
Nome do projeto, descrição em uma linha e badges (Python version, License, Build status).
Comandos claros: uv pip install git+https://github.com/usuario/repo ou clone + install local.
JSON exato para adicionar ao claude_desktop_config.json, com variáveis de ambiente necessárias.
Lista de todas as tools com descrição e exemplos de prompts que o usuário pode usar no Claude.
Use o teste dos 30 segundos: se alguém não conseguir entender o que seu server faz e como instalá-lo em 30 segundos lendo o README, ele precisa ser reescrito. Coloque o comando de instalação e a configuração do Claude Desktop logo no início — são as informações mais buscadas.
Um projeto sem licença é, por padrão, todos os direitos reservados — ninguém pode legalmente usar, modificar ou distribuir seu código. Adicionar uma licença open source é essencial para que a comunidade possa contribuir e usar seu MCP Server. Além disso, guidelines de contribuição ajudam a manter a qualidade do projeto.
A licença MIT é a escolha mais popular para projetos open source — é simples, permissiva e permite uso comercial. Basta criar um arquivo LICENSE na raiz do projeto com o texto padrão da MIT. Para contribuições, um CONTRIBUTING.md deve explicar como reportar bugs, sugerir features e enviar pull requests. Opcionalmente, um CODE_OF_CONDUCT.md estabelece regras de convivência para a comunidade.
A MIT License é usada em mais de 44% dos projetos open source no GitHub, seguida pela Apache 2.0 (18%) e GPL 3.0 (9%). Projetos com licença clara recebem 3x mais contribuições do que projetos sem licença. A maioria dos MCP Servers publicados pela comunidade usa MIT — é o padrão de fato para esse ecossistema.
GitHub Actions permite automatizar testes e verificações a cada push ou pull request. Para um MCP Server, um workflow básico de CI (Continuous Integration) garante que o código passa no linter, o pacote constrói sem erros e os imports funcionam corretamente. Isso previne que código quebrado chegue à branch principal.
Um workflow YAML simples para CI do MCP Server:
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"
Este workflow instala dependências, roda o linter ruff, testa o build e verifica que o pacote é importável. Salve em .github/workflows/ci.yml.
Use astral-sh/setup-uv para configurar o uv no GitHub Actions — é a forma mais rápida de instalar dependências Python em CI. O ruff é o linter mais rápido do ecossistema Python e cobre as mesmas regras do flake8, isort e pyupgrade em um único binário.
Nunca coloque segredos diretamente no workflow YAML. Se seu MCP Server precisa de chaves de API para testes, use GitHub Secrets (Settings → Secrets → Actions) e referencie-os como ${{ secrets.API_KEY }} no workflow. Segredos hardcoded em workflows são visíveis para qualquer pessoa com acesso ao repositório.
Tags e releases são a forma profissional de marcar versões estáveis do seu projeto. Uma tag Git marca um ponto específico no histórico; um GitHub Release combina essa tag com notas de changelog, permitindo que usuários identifiquem e instalem versões específicas do seu MCP Server.
O fluxo de criação de uma release:
# 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 (versionamento semântico): v0.1.0 para primeira release, incrementando PATCH para fixes, MINOR para features e MAJOR para breaking changes. No GitHub, crie um Release a partir da tag com changelog descrevendo o que mudou.
Atualizar a versão no pyproject.toml e commitar a mudança.
Criar tag anotada com git tag -a e fazer push para o remote com --tags.
No GitHub, criar Release a partir da tag com changelog descrevendo bugs corrigidos, features adicionadas e breaking changes.
Mantenha um formato consistente de changelog nas releases. Use categorias como "Added", "Fixed", "Changed" e "Breaking" para que os usuários saibam rapidamente o que mudou. O formato Keep a Changelog é uma referência excelente.
O teste final antes de anunciar seu MCP Server é o teste do clone limpo: clonar o repositório em uma pasta diferente (ou outra máquina), seguir exatamente as instruções do README e verificar que tudo funciona. Se você não conseguir instalar seguindo seu próprio README, ninguém mais vai conseguir.
O teste de instalação simula a experiência de um novo usuário:
# 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
Se qualquer passo falhar, atualize o README ou corrija o problema antes de publicar. O teste deve cobrir: instalação, execução, configuração no Claude Desktop e pelo menos uma chamada de tool funcionando.
Clonar o repositório em pasta temporária e verificar que a estrutura está completa.
Instalar seguindo exatamente o README — sem passos extras que "você sabe" mas não documentou.
Rodar o server, configurar no Claude Desktop e executar pelo menos uma tool com sucesso.
Próximo Módulo: 5.3 — Transporte HTTP/SSE