vagas-mcp

Servidor MCP (Model Context Protocol) que dá ao Claude ferramentas para organizar uma busca de emprego: registrar vagas, acompanhar o status, medir o funil de conversão e lembrar dos follow-ups.

O problema

Quem está buscando emprego aplica para dezenas de vagas em plataformas diferentes (Gupy, LinkedIn, sites próprios) e perde o controle: onde já apliquei? Quem não respondeu há duas semanas? Minha taxa de entrevista está boa?

Com o vagas-mcp conectado, dá para conversar com o Claude assim:

"Registra a vaga de Analista de IA Jr da Empresa X que achei na Gupy, é remota." "Apliquei na vaga 3 hoje." "Como está meu funil?" "Quais candidaturas estão paradas há mais de 10 dias?"

E o Claude chama as ferramentas certas, com os dados guardados localmente em SQLite.

Related MCP server: JobDesk MCP Server

Demo

arthurpenedo.github.io/vagas-mcp — sessão real com o servidor rodando por stdio (como no Claude Desktop), gerada pelo CI a cada push: cada chamada de ferramenta e a resposta que o servidor devolveu, o funil e o relatório semanal. Empresas fictícias.

O que o servidor expõe

As três primitivas do MCP:

Arquitetura

Claude Desktop / Claude Code ──(MCP, stdio)──► server.py (MCPServer: casca fina)
                                                     │
                          ┌──────────────────────────┼──────────────────────────┐
                          ▼                          ▼                          ▼
               store.py (regras + SQLite)   ats-match (aderência)    notion.py (API do Notion)
               tabelas: vagas, historico    extra opcional [ats]     SQLite → Notion, upsert

Decisões técnicas

• Regra de negócio separada do protocolo. store.py não sabe o que é MCP e é testado diretamente; server.py só traduz ferramentas em chamadas. Trocar de protocolo (API REST, CLI) não mexe na lógica.

• Funil pelo histórico, não pelo status atual. Uma vaga que chegou à entrevista e depois foi recusada conta como entrevista no funil. Olhar só o status atual subestimaria a conversão.

• Local-first. SQLite num arquivo do usuário, sem conta nem servidor externo. As instruções do servidor orientam o modelo a não registrar dados sensíveis.

• Erros que o modelo consegue corrigir. No MCP SDK 2.x, uma exceção comum vira um "Error executing tool" genérico e a mensagem fica no servidor. As regras de negócio (link duplicado, vaga inexistente, status inválido) são convertidas em ToolError, então o Claude recebe "Já existe uma vaga com este link (id 8)" e pode se corrigir. A demo mostra esse caso.

• Notion sem template obrigatório. O sincronizador lê o schema do banco antes de escrever e preenche cada coluna conforme o tipo dela (título, texto, select, status, URL, data). Coluna que não existe é ignorada com aviso; opção de status que não existe no Notion (a API não deixa criar) é pulada em vez de derrubar a sincronização. Vagas já cadastradas à mão são encontradas pelo link, sem duplicar.

• SQLite como fonte da verdade, Notion como vitrine. Mão única: funciona offline e é testável; o Notion serve para acompanhar pelo celular.

• Migração sem perder dados. Bancos da v0.1 ganham as colunas novas na abertura (ALTER TABLE só se faltar).

• Testes pelo protocolo. Os testes usam o cliente MCP do SDK contra o servidor em memória, a API do Notion é simulada com httpx.MockTransport, e a demo sobe o servidor por stdio de verdade no CI.

Como usar

git clone https://github.com/arthurpenedo/vagas-mcp && cd vagas-mcp
pip install -e ".[dev]"          # servidor + testes
pip install -e ".[dev,ats]"      # + analisar_aderencia (instala o ats-match do GitHub)
pytest -q
python scripts/demo.py site/index.html   # gera a página da demo

Claude Code:

claude mcp add vagas -- vagas-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "vagas": { "command": "vagas-mcp", "env": { "VAGAS_DB": "C:/Users/voce/vagas.sqlite3" } }
  }
}

O banco fica em VAGAS_DB (padrão: ~/.vagas-mcp/vagas.sqlite3).

Notion (opcional): crie uma integração interna, compartilhe o banco com ela e defina NOTION_TOKEN e NOTION_DATABASE_ID no env acima. Os nomes de coluna esperados (Vaga, Empresa, Plataforma, Nível, Modelo, Link, Status, Data, Notas) ficam em notion.CAMPOS.

Próximos passos

• Sincronização com um banco do Notion

• Ferramenta de aderência integrada ao ats-match

• Resource com o relatório semanal e prompt de revisão

• Demo pública gerada no CI com sessão stdio real

• Importar do Notion (mão dupla)

• Vídeo de demonstração no Claude Desktop

Feito por Arthur Penedo · LinkedIn