LinkedIn Job Search for Claude

An autonomous MCP server that continuously scrapes LinkedIn jobs and provides instant database-backed queries. Features background scraping profiles, application tracking, and composable response models.

Features

MCP Server (Backend)

• Autonomous background scraping — Configurable profiles that scrape continuously

• SQLite database with FTS5 full-text search and WAL mode for concurrent access

• 11 MCP tools organized into 4 categories: Query, Profile Management, Application Tracking, Analytics

• Cache-first serving — Instant (<100ms) queries from local database

• Async HTTP scraping with httpx (no browser required)

• Composable Pydantic models — Token-efficient responses with exclude_none=True

Integrated Features

1. Job Querying — Composable filters (company, location, keywords, remote, visa, posted date)

2. Live Exploration — On-demand scraping for 1-10 most recent jobs

3. Profile Management — Add/update/delete autonomous scraping profiles

4. Application Tracking — Track application status and notes

5. Company Enrichment — Automatic company metadata lookup

6. Job Change Detection — Audit log for field changes over time

7. Analytics — Database statistics and scraping profile health

Related MCP server: LinkedIn MCP Server

Prerequisites

• Python 3.13+

• Pixi for dependency management

• uv for building MCP bundles (optional)

Installation

Clone the repository and install dependencies with Pixi:

git clone https://github.com/francisco-perez-sorrosal/linkedin-mcp.git
cd linkedin-mcp
pixi install

Project Structure

linkedin-mcp/
├── src/linkedin_mcp_server/
│   ├── main.py                  # FastMCP server with 11 async tools
│   ├── db.py                    # SQLite database layer with FTS5 search
│   ├── background_scraper.py    # Autonomous background scraping service
│   ├── scraper.py               # Async HTTP scraper (httpx + BeautifulSoup)
│   ├── models.py                # Pydantic response models (composable)
│   └── migrate_cache.py         # JSONL → SQLite migration script
├── skills/
│   └── linkedin-job-search/     # Job search orchestration skill
│       ├── SKILL.md
│       └── references/
│           └── tool-mapping.md
├── tests/
│   ├── test_db.py               # Database unit tests (37 tests)
│   ├── test_scraper.py          # Scraper parsing tests (33 tests)
│   ├── test_background_scraper.py  # Background scraper tests (17 tests)
│   ├── test_integration.py      # End-to-end tests (6 tests)
│   ├── test_migrate_cache.py    # Migration tests (7 tests)
│   ├── test_models.py           # Pydantic model tests (17 tests)
│   └── fixtures/                # HTML fixtures for tests
└── pyproject.toml

Running the Server

Local Development

# stdio transport (for local Claude Desktop integration)
pixi run mcps --transport stdio

# streamable-http transport (for remote access)
pixi run mcps --transport streamable-http

# Direct execution with uv
uv run --with "mcp[cli]" mcp run src/linkedin_mcp_server/main.py --transport streamable-http

The HTTP server runs at http://localhost:10000/mcp by default.

MCP Inspection Mode

DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector pixi run mcps --transport stdio

Development Tasks

pixi run test      # Run tests
pixi run lint      # Check linting
pixi run format    # Apply formatting and fix lint issues
pixi run build     # Build package (creates sdist/wheel in dist/)

MCP Tools

The server exposes 11 tools organized into 4 categories. For detailed tool comparison, default parameters, and usage patterns, see skills/linkedin-job-search/references/tool-mapping.md.

Job Query Tools

1. explore_latest_jobs

Live scraping for 1-10 most recent jobs (10-30 seconds).

explore_latest_jobs(
    keywords="AI Engineer or ML Engineer or Principal Research Engineer",
    location="San Francisco, CA",
    distance=25,  # miles
    limit=1       # max 10
)

2. query_jobs

Instant database queries with composable filters (<100ms).

query_jobs(
    company="Anthropic",
    location="San Francisco",
    keywords="ML Engineer",
    posted_after_hours=168,  # Last week
    remote_only=True,
    visa_sponsorship=True,
    limit=20,
    sort_by="posted_date_iso",
    include_description_insights=True,
    include_metadata=False,
    include_full_description=False
)

Profile Management Tools

3. add_scraping_profile

Add autonomous scraping profile (worker spawns within 30s).

4. list_scraping_profiles

List all scraping profiles with status.

5. update_scraping_profile

Update profile configuration (changes apply on next reload).

6. delete_scraping_profile

Disable (soft delete) or permanently delete profile.

Application Tracking Tools

7. mark_job_applied

Track job application with optional notes.

8. update_application_status

Update status (applied → interviewing → offered/rejected).

9. list_applications

Query applications by status.

Analytics Tools

10. get_cache_analytics

Database statistics, scraping profile health, application counts.

11. get_job_changes

Audit log of field changes over time.

Claude Desktop Integration

Local Configuration (stdio)

Add to claude_desktop_config.json:

{
  "linkedin_mcp_fps": {
    "command": "uv",
    "args": [
      "run",
      "--with", "mcp[cli]",
      "--with", "pymupdf4llm",
      "mcp", "run",
      "src/linkedin_mcp_server/main.py",
      "--transport", "streamable-http"
    ]
  }
}

Remote Configuration (HTTP)

For connecting to a remote MCP server:

{
  "linkedin_mcp_fps": {
    "command": "npx",
    "args": ["mcp-remote", "http://localhost:10000/mcp"]
  }
}

Replace the host and port as needed for your deployment.

MCP Bundle (mcpb)

Build and install as an extension:

pixi run mcp-bundle
pixi run pack

The output file linkedin-mcp-fps.mcpb is created in mcpb-package/. Double-click to install in Claude Desktop.

Claude Code Skills

Client-side skill for workflow orchestration (located in skills/):

linkedin-job-search

Interactive workflow for job searching:

• Step 1: Gather search parameters (keywords, location, distance, limit)

• Step 2: Choose between live exploration or database query

• Step 3: Present results in scannable table

• Step 4: Refine search with different filters

• Step 5: Offer next actions

Activate with: "find jobs", "search positions", "job hunt".

See skills/linkedin-job-search/SKILL.md for detailed documentation.

Architecture

1. MCP Server (main.py)

• Built with FastMCP framework

• Configurable transport modes: stdio, streamable-http

• 11 async tools for job querying, profile management, application tracking, and analytics

• Cache-first serving: queries return instantly from SQLite database

• Auto-detects transport mode from environment variables

2. Database Layer (db.py)

• SQLite with WAL mode for concurrent reads/writes

• FTS5 full-text search on job descriptions and titles

• 5 tables: jobs, scraping_profiles, applications, company_enrichment, job_changes

• Default location: ~/.linkedin-mcp/jobs.db

• Composable queries with multiple filters

• Performance: <100ms for typical queries

3. Background Scraper Service (background_scraper.py)

• Runs continuously in MCP server process (async tasks)

• One worker per scraping profile (configurable via MCP tools)

• Default profile: San Francisco, CA, 25mi, "AI Engineer or ML Engineer or Principal Research Engineer", 2h refresh

• Semaphore(10) for job scraping, Semaphore(2) for company enrichment

• Adaptive rate limiting with exponential backoff

• Graceful startup/shutdown with asyncio task coordination

4. Web Scraper (scraper.py)

• Async httpx for LinkedIn Guest API (no Selenium required)

• Enhanced extraction: salary parsing, remote/visa detection, skills extraction

• Company name normalization for fuzzy matching

• Frozen dataclasses for type safety: JobSummary, JobDetail

• Rate limiting with random delays (1-3s) and exponential backoff

LinkedIn API Endpoints

The system uses LinkedIn's guest API:

• Job search: https://www.linkedin.com/jobs-guest/jobs/api/seeMoreJobPostings/search-results/

• Job details: https://www.linkedin.com/jobs-guest/jobs/api/jobPosting/{job_id}

Parameters:

• location: Search location (URL encoded)

• distance: Radius in miles (10, 25, 35, 50, 75, 100)

• keywords: Job search query (URL encoded)

• start: Pagination offset

• Optional filters: f_E (experience), f_JT (job type), f_WT (work arrangement), f_TPR (time posted)

Dependencies

Removed: selenium, requests, jsonlines, pyyaml (cache.py deleted, moved to SQLite)

All dependencies are managed via Pixi (see pyproject.toml).

Migration from JSONL Cache

If you have existing JSONL cache from v0.2.0, run the migration script:

pixi run python src/linkedin_mcp_server/migrate_cache.py

This will:

• Backup existing JSONL cache (creates .jsonl.backup)

• Migrate all jobs to SQLite database at ~/.linkedin-mcp/jobs.db

• Transform and populate enhanced fields (salary, remote, visa, skills)

• Preserve all original job data

The migration is idempotent and can be safely rerun. After migration, the JSONL cache is no longer used.

Deployment

Remote Deployment (render.com)

Set environment variables in the deployment dashboard:

TRANSPORT=streamable-http
PORT=10000

Generate requirements.txt for render.com:

uv pip compile pyproject.toml > requirements.txt

Add runtime.txt with:

python-3.13.0

Usage Examples

Query Cached Jobs

Find remote ML Engineer jobs at Anthropic posted in the last week

Live Exploration

Explore the 5 most recent AI Engineer jobs in Seattle

Profile Management

Add a scraping profile for Research Engineer jobs in Boston, 35 mile radius, refresh every 4 hours

Application Tracking

Mark job 1234567890 as applied with note "Applied via company website"

Update application status for job 1234567890 to interviewing with note "Phone screen scheduled for Friday"

Analytics

Show me cache analytics and scraping profile status

Using Skills

@linkedin-job-search Find remote Python Engineer jobs in New York

Troubleshooting

Future Enhancements

Additional Client-Side Skills

Create workflow orchestration skills for uncovered tool categories:

• Profile Management Skill — Interactive workflow for configuring autonomous scraping profiles

• Application Tracking Skill — Guide user through marking applications and tracking status changes

• Analytics Skill — Present cache statistics and job trends in scannable format

Currently, only job search has a dedicated skill. Other tools are accessed directly via MCP.

See CLAUDE.md Future Enhancements section for additional features (duplicate detection, ML scoring, proxy support, etc.).

Support

For issues and feature requests, visit: https://github.com/francisco-perez-sorrosal/linkedin-mcp

License

MIT License. See pyproject.toml for details.