Job Assistant MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Job Assistant MCP Find Python + AI jobs posted this week and tell me which three fit me best."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Job Assistant MCP
An MCP server that turns Claude into a job-search assistant. It pulls real postings from public job boards, scores them against your own stored profile (skills, experience, projects) and tracks your applications in SQLite.
"Find remote Python + AI jobs posted this week and tell me which three fit me best."
What it does
Tool | Purpose |
| Store your skills, years of experience, target roles, summary and projects (merged, so you can update one field at a time). |
| Query all boards concurrently, filter by keywords / remote / recency, dedupe, cache. If a profile exists every result gets a 0-100 fit score and the list is sorted best-first. |
| Explainable breakdown for one posting: matched & missing skills, seniority fit, which of your projects to mention. |
| Full posting text + your application status. |
| Application tracker ( |
Also exposed: resources profile://me and jobs://pipeline, and prompts find_best_jobs and
prepare_application (tailored cover letter + talking points).
Job sources
Source | Access | Notes |
official public RSS | Ukrainian IT jobs | |
official public RSS | Ukrainian / European IT jobs |
The scope is intentionally limited to these two Ukrainian IT job boards. LinkedIn is not supported: it has no public job API and scraping it violates its Terms of Service. New sources are easy to add, see Adding a source.
A failing board never breaks a search; its error is reported in errors and the rest still return.
Related MCP server: cv-job-assistant
Quick start
You need Docker and an MCP client such as Claude Code.
1. Start the server
git clone https://github.com/kaidashova/job-assistant-mcp.git && cd job-assistant-mcp
docker compose up -d --buildThe MCP endpoint is now at http://localhost:8000/mcp. If port 8000 is taken, pick another one:
HOST_PORT=8765 docker compose up -d --build (use the same port in step 2).
2. Connect your MCP client
claude mcp add --transport http job-assistant http://localhost:8000/mcp
claude mcp list # job-assistant should show as connectedThen start claude and type /mcp to see the 8 tools. Any other MCP client that supports
Streamable HTTP can use the same URL.
3. Day-to-day
docker compose logs -f # watch the server
docker compose down # stop (your data is kept)
docker compose down -v # stop and delete all data (profile, applications)The container restarts automatically with Docker. Your profile and applications live in the
job-data Docker volume, so they survive restarts and rebuilds.
The port is bound to 127.0.0.1 only. There is no authentication, so don't expose it publicly
without a reverse proxy in front.
Try it
Tell Claude about yourself once:
Save my profile: skills Python, FastAPI, PostgreSQL, Docker, LLM, RAG, MCP; 3 years of experience; I want Python Developer or AI Engineer roles. Projects: "Job Assistant MCP" (MCP server, tech: python, sqlite, mcp), "Docs Q&A bot" (tech: python, rag, postgresql).
Use the
find_best_jobsprompt, or just ask:Find remote Python + AI jobs posted this week and tell me which three fit me best.
Save the first one and mark it as applied. → later: "What's in my pipeline?"
How scoring works
Deterministic and explainable, so Claude can reason over the parts instead of a black box:
score = 65 × skill coverage + 20 × role fit + 15 × seniority fit
Skill coverage: skills are extracted from the posting using a vocabulary of ~90 technologies with aliases (
k8s → kubernetes,postgres → postgresql; ambiguous words like go only match asgolang). Skills in the title/tags count double. Umbrella skills are implied (LLM/RAG ⇒ AI, PostgreSQL ⇒ SQL). Skills outside the vocabulary that you list in your profile are still searched for.Role fit: word overlap between your target roles and the job title.
Seniority fit: level from the title (junior … lead) vs. your years of experience.
Architecture
Layered, with dependencies pointing downward only:
server/ MCP adapters: tools, resources, prompts (validate input -> call service -> typed output)
↓
services/ business logic: SearchService, TrackerService, ProfileService, MatchingService
↓
repositories/ SQLite access only: Database, JobRepository, ApplicationRepository, ProfileRepository
sources/ one module per job board, all behind the same JobSource protocol
matching/ pure scoring engine + skill extraction (no I/O)
utils/ small stateless helpers (HTML to text, date parsing)
schemas/ Pydantic models shared by every layer; tool results are typed, so the server
publishes JSON output schemas for each tool
constants/ all module-level constants (skill vocabulary, scoring weights, feed URLs, SQL schema…)
config.py Settings (pydantic BaseSettings, read from env / .env)
container.py composition root: builds the repositories and services and wires them together
errors.py JobAssistantError, surfaced to the model as a clean tool errorapp/
config.py container.py errors.py
constants/ skills, matching, sources, search, database, server
schemas/ job, application, profile, search, matching, source
repositories/ database, jobs, applications, profile
services/ search, tracker, profile, matching, filters
matching/ scoring, skills
sources/ base, rss, dou, djinni
utils/ text (HTML cleanup, remote detection), dates
server/ app, tools, resources, prompts
tests/ offline: mocked HTTP + fixtures, one test module per layer, plus end-to-end over MCPServices never import MCP and the server never touches SQL, so each layer is testable on its own.
Development
make install # local .venv with dev tools (uv)
make test # offline tests, no network needed
make lint # ruff + mypyCI (GitHub Actions) runs lint + tests on Python 3.11-3.13 and builds the Docker image.
Adding a source
Create app/sources/mysource.py with a class that has a name and an
async fetch(client, query) -> list[Job], then register it in sources/__init__.py. Filtering by
keyword / remote / date is done centrally in services/filters.py, so a source only needs to fetch and map
fields. Add a fixture and a test in tests/.
Configuration
Variable | Default | Meaning |
|
| SQLite file |
|
|
|
|
| HTTP bind address inside the container |
|
| Seconds before a job-board request times out |
To change one, add it under environment: in docker-compose.yml and run docker compose up -d again.
Notes
Built on the official MCP Python SDK (v2,
MCPServer).Be a good citizen: only public feeds/APIs are used, with a descriptive User-Agent and one request per board per search.
Your profile and applications never leave your machine; only the search keywords go to the boards.
MIT licensed.
Available Tools
8 toolsget_jobARead-only
Full details (description, tags, application status) of a job from search results.
Inputs: job_id (required). Returns: id, url, tags, title, +8 more
get_profileARead-only
Return the stored profile (empty if none has been set yet).
Inputs: no named parameters. Returns: skills, summary, projects, target_roles, +1 more
list_applicationsBRead-only
Your tracked jobs (optionally filtered by status) plus counts per pipeline stage.
Inputs: status. Returns: counts, applications
match_job_to_profileBRead-only
Compare a posting with the stored profile: score, matched/missing skills, seniority fit and which of your projects are most relevant to mention.
Inputs: job_id (required). Returns: url, notes, score, title, +7 more
save_jobBIdempotent
Add a job to your application tracker with status 'saved'.
Inputs: job_id (required), notes. Returns: application, already_saved
search_jobsA
Search live job boards concurrently. If a profile is stored, each result carries a 0-100 fit score and results are sorted best-first; otherwise newest-first.
Inputs: keywords (required), limit, sources, remote_only, +2 more. Returns: jobs, errors, returned, by_source, +2 more
set_profileBIdempotent
Create/update your profile. Only the fields you pass are changed.
Inputs: skills, summary, projects, target_roles, +1 more. Returns: skills, summary, projects, target_roles, +1 more
update_statusBIdempotent
Move a job through the pipeline; every change is kept in its history.
Inputs: job_id (required), status (required), notes. Returns: url, notes, title, job_id, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource and action: profile (get/set), jobs (search/get/save/match), and applications (update_status/list_applications). The fit-scoring overlap between search_jobs and match_job_to_profile is intentional and clearly separated by scope. An agent can reliably pick the right tool for any task.
All tools use a consistent snake_case verb_noun pattern (get_profile, search_jobs, save_job, list_applications, set_profile, update_status). Naming is predictable and self-describing throughout.
8 tools is well-scoped for a job-assistant domain covering profile management, job discovery, matching, and application tracking. No redundant or filler tools; each earns its place.
Covers the core lifecycle: profile get/set, job search/get/match/save, and application tracking with status updates and counts. Minor gaps exist (no way to remove/unsave a job or delete a profile), but agents can work around them.
Maintenance
Related MCP Connectors
Track job applications on a board: let Claude or ChatGPT read and update jobs, interviews, notes.
Run your tech job search from your AI agent: matches, job unlocks, applications and follow-ups.
Job search tracker for Claude and ChatGPT: applications, interviews, follow-ups, company watch.
Analyze job listings against your resume, track applications, and generate cover letters.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables searching justjoin.it for job listings and tracking applications locally with status updates, all via natural language in Claude.4MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to parse CVs, search job boards (Remotive, Arbeitnow, Adzuna, Greenhouse/Lever), tailor resumes and cover letters, and prepare application packages with direct apply links—without ever auto-submitting. It runs 100% locally and free, storing jobs and applications as JSON files.-
- FlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to manage a job search end-to-end: find and score job listings, tailor resumes, generate application messages, and track application history, while leaving final external actions to the user.-
- AlicenseBqualityBmaintenanceEnables Claude to search job listings on selected sites, filter and score them against your own skills, track application status, and generate a tailored LaTeX/PDF resume for each job. It also supports importing an existing Word or PDF resume and diagnosing local setup, all with data kept in a private folder on your own machine.12MIT