Beacon MCP – Gerenciador de Perfil e Busca de Empregos
odanree/beacon-mcp
Gerencie seu perfil Beacon e pipeline de empregos via Claude, sem terminal.
Ver no GitHubServidor MCP que expõe a API REST do Beacon (pipeline de busca de empregos) para Claude Code, permitindo adicionar projetos ao perfil, listar e inspecionar vagas conversacionalmente. Elimina a necessidade de chamar curl + JWT manualmente, transformando operações complexas em prompts naturais.
Instalação
npx convez-ai odanree/beacon-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Adicionar projetos ao portfólio durante sessões de chat com Claude
- Listar e filtrar vagas por estágio do pipeline (screen, interview, etc)
- Inspecionar detalhes completos de uma vaga (JD, histórico, etc)
- Automação de atualização de perfil profissional sem sair do IDE
Veredito

Solução bem arquitetada para quem usa Beacon + Claude Code. Reduz significativamente o atrito operacional ao converter fluxos curl complexos em prompts naturais. Cobertura de testes sólida (9 testes com mocks via respx) e autenticação JWT já considerada; pronto para uso em produção com extensões planejadas (busca + resume generator).
README
A tradução para o português deste README ainda está na fila.
beacon-mcp
MCP server wrapping the Beacon job-search-pipeline REST API so Claude Code can add projects, list/inspect jobs, and (eventually) drive the resume generator without me ever opening a terminal to write curl and a JWT heredoc again.
MCP · FastMCP · Beacon · Claude Code · Pydantic v2 · httpx · respx
| Tool | What it does |
|---|---|
beacon_add_project | POST /api/profile/projects — capture a project for resume generation |
beacon_list_projects | GET /api/profile/projects — see what's already on the profile |
beacon_list_jobs | GET /api/jobs filtered by pipeline status |
beacon_get_job | GET /api/jobs/{id} — full record + JD text |
Why this exists
I added three portfolio projects to my Beacon profile during a single Claude session. Each one was 80 lines of curl + JSON-body + JWT-cookie-from-DevTools + bash-heredoc-syntax-vs-PowerShell. Three times. With encoding errors and reshuffled apostrophes.
This server reduces every one of those incidents to:
"Add a Beacon project — name: infra-mcp, url: https://github.com/odanree/infra-mcp, tech stack: MCP / FastMCP / pytest, outcome: …"
The model fills the schema, the tool POSTs, done.
Auth
Beacon uses Google OAuth → JWT. Easiest way to get the token:
- Sign in to your Beacon instance in the browser
- DevTools → Application → Cookies → copy the value of
access_token - Paste into
.envasBEACON_JWT=…(and setBEACON_API_URLto your deployment)
When the token expires (typically 24h–30d depending on your config) any tool call returns {"ok": false, "error_kind": "auth", "error": "..."} and the model knows to ask you to refresh. The error message includes the exact step to do so.
Install
git clone https://github.com/odanree/beacon-mcp
cd beacon-mcp
python -m venv .venv
.venv/Scripts/activate
pip install -e ".[dev]"
cp .env.example .env # paste BEACON_JWT
Register with Claude Code (user-scope)
claude mcp add beacon -s user -- "/abs/path/to/beacon-mcp/.venv/Scripts/python.exe" -m server.main
claude mcp list
Try:
"List my Beacon projects."
"Add a new Beacon project — name 'beacon-mcp', url 'https://github.com/odanree/beacon-mcp', tech stack ['MCP', 'FastMCP', 'pytest-asyncio'], outcome '4 tools, 9 tests, replaces the curl+JWT+heredoc dance every time I want to update my resume profile.'"
"List my jobs in the screen stage."
Tests
pytest
# All HTTP mocked via respx — no network calls, no real Beacon hits.
9 tests covering:
- Authenticated POST flows (project create)
- 401 vs 5xx error mapping (clear error kinds —
authvshttp) - Missing JWT detection at the client boundary
- Pagination + status filter param passing
- Both envelope shapes Beacon endpoints can return (
[…]and{items: […]})
Roadmap
beacon_search_jobs(query)— natural-language job search, once Beacon's search endpoint stabilizesbeacon_generate_resume(job_id)— kick the resume generator for one JD and return the markdownbeacon_score_resume(jd_text)— score arbitrary JD text against the user's profile (good for quick "should I apply?" calls)- Move JWT from .env to keyring storage on the host
License
MIT