Yabot Jobs MCP server

A remote MCP server that lets an MCP client (Claude Desktop, Claude Code, etc.) search jobs, apply to one, store a fit evaluation of your resume against a job that the client computed itself, and upload an HTML tailored resume / cover letter you've drafted — all against your own Yabot Jobs account.

It's a thin process: every tool call is an HTTP request to the FastAPI backend (main.py), authenticated with a short-lived personal access token minted for that connection via OAuth. It never touches the database directly.

1. Install dependencies

From the repo root, into the existing venv (or a separate one — this package only needs mcp and httpx):

.venv/bin/pip install -r requirements.txt

Related MCP server: jobfinder-mcp

2. Start the backend and frontend

The MCP server calls the API (defaults to http://localhost:8000), and the OAuth consent screen lives on the web frontend (defaults to http://localhost:3000) — both need to be running and reachable:

# in yabot.jobs-backend/
.venv/bin/python main.py

# in yabot.jobs-frontend/
npm run dev

3. Configure and run this server

YABOT_API_BASE_URL=http://localhost:8000 \
YABOT_FRONTEND_BASE_URL=http://localhost:3000 \
YABOT_MCP_PUBLIC_URL=http://localhost:8080 \
.venv/bin/python server.py

(Or put these in this repo's .env — server.py loads it automatically via python-dotenv.) YABOT_MCP_PUBLIC_URL must be this server's own publicly reachable URL once deployed (its OAuth issuer identity) — http://localhost:8080 only works for local testing.

4. Connect it to Claude

No token to mint or paste — Claude does OAuth dynamic client registration and a browser-based login automatically the first time it connects, reusing the backend's existing magic-link login (see app/services/auth.py/app/api/routes/oauth.py in yabot.jobs-backend and OAuthAuthorizePage.tsx in yabot.jobs-frontend for the consent screen).

Claude Code

claude mcp add --transport http yabot-jobs http://localhost:8080/mcp

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "yabot-jobs": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Restart Claude Desktop after saving. On first use, Claude opens a browser tab pointed at the frontend's consent screen; log in (or you're already logged in) and click Approve. In production, use this server's real public HTTPS URL instead of localhost.

Fallback: minting a token by hand

create_token.py still works standalone against the backend (drives the magic-link login, then POST /auth/tokens) for scripts or CI that want a long-lived personal access token instead of going through OAuth — it's unrelated to how Claude itself connects to this server now.

Tools

upload_tailored_resume / upload_cover_letter take structured content, not markup — no HTML/Markdown. Tailored resumes: summary (string) plus sections (a list of {heading, bullets} objects). Cover letters: greeting, body_paragraphs (a list of strings), closing. This matches the shape the backend's own LLM generates and the frontend already expects (TailoredResume/CoverLetter.content in the frontend's src/api/types.ts) — see app/services/resume_renderer.py for how it's rendered.

Deploying to Cloud Run

This repo ships a Dockerfile and a .github/workflows/deploy.yml that builds the image, pushes it to Artifact Registry, and deploys it to Cloud Run on every push to main (or manually via "Run workflow").

Deploy target: project yabotjobs, region us-central1, service yabot-jobs-mcp.

One-time setup (creates the Artifact Registry repo, a dedicated deploy service account, and Workload Identity Federation so GitHub Actions never needs a stored key):

gcloud auth login
GITHUB_REPO=davicho01/yabot.jobs-mcp ./deploy/setup-gcp.sh

It prints the two values to add as GitHub Actions secrets:

• GCP_WORKLOAD_IDENTITY_PROVIDER

• GCP_SERVICE_ACCOUNT

And three GitHub Actions variables (Settings → Secrets and variables → Actions → Variables) — these become the container's env vars, so use real production URLs, not localhost:

• YABOT_API_BASE_URL — the deployed backend's URL

• YABOT_FRONTEND_BASE_URL — the deployed frontend's URL

• YABOT_MCP_PUBLIC_URL — this service's own public Cloud Run URL (fill this in after the first deploy, then re-run the workflow so the OAuth issuer identity matches)

Once the secrets and variables are set, push to main to deploy.