Skip to main content
Glama
francisco-perez-sorrosal

LinkedIn MCP Server

by francisco-perez-sorrosal
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Hybrid

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

Package

Version

Role

httpx

>=0.28.1,<0.29

Async HTTP client for LinkedIn API

mcp[cli]

>=1.9.2,<2

FastMCP framework

beautifulsoup4

>=4.13.4,<5

HTML parsing

pydantic

>=2.10.6,<3

Composable response models with exclude_none

loguru

>=0.7.3,<0.8

Structured logging

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

Issue

Solution

Import errors

Run pixi install to install dependencies

Database locked

Another process may have the database open; close other connections

Background scraper not running

Check logs; verify profile is enabled in list_scraping_profiles()

Empty query results

Database may be empty; wait for first scrape or use explore_latest_jobs()

Rate limiting (429/503)

Automatic backoff; check logs for error rates

Permission errors

Ensure ~/.linkedin-mcp/ directory is writable

Migration failed

Restore from .jsonl.backup and retry; check logs for errors

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.

Available Tools

4 tools
adapt_cv_to_latest_jobC
Adapts Francisco Perez-Sorrosal's CV to the position of the job description retrieved from linkedin 
for the particular location specified and based on the job id.

Args:
    position: The position to search for jobs for
    location: The location where the job should be located
    job_id: The job id to retrieve the metadata for
    
Returns:
    str: The job details and the generated adapted CV tailored to the job description
ParametersJSON Schema
NameRequiredDescriptionDefault
job_idNofirst
locationNoSan Francisco
positionNoResearch Engineer or ML Engineer or AI Engineer

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool adapts a CV and returns job details with an adapted CV, but lacks critical behavioral details: it doesn't specify if this is a read-only or mutation operation (though 'adapts' suggests generation, not modification), what permissions or authentication are needed, rate limits, or how the adaptation process works (e.g., AI-based, template-based). This leaves significant gaps for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and well-structured: it starts with a clear purpose statement, followed by separate 'Args' and 'Returns' sections. Each sentence adds value without redundancy. However, it could be slightly more front-loaded by integrating parameter roles into the initial statement for faster comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (CV adaptation tool with 3 parameters), no annotations, no output schema, and 0% schema description coverage, the description is incomplete. It covers the basic purpose and parameters but misses behavioral context (e.g., how adaptation works, side effects), detailed parameter guidance, and output specifics beyond a string return. For a tool that likely involves data processing and generation, this leaves too many unknowns for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an 'Args' section that lists the three parameters (position, location, job_id) and a 'Returns' section stating the output is a string with job details and adapted CV. However, schema description coverage is 0%, meaning the input schema provides no descriptions for parameters. The description adds basic semantics by naming the parameters and their roles, but doesn't elaborate on formats (e.g., what 'job_id' refers to), constraints, or examples, which is insufficient to fully compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: adapting a specific person's CV to a job description retrieved from LinkedIn based on position, location, and job ID. It specifies the verb ('Adapts'), resource ('Francisco Perez-Sorrosal's CV'), and target ('job description retrieved from linkedin'). However, it doesn't explicitly differentiate from sibling tools like get_jobs_raw_metadata or get_new_job_ids, which appear to be related to job data retrieval rather than CV adaptation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing job data from siblings), exclusions, or comparisons to other tools. The context implies it might follow job retrieval tools, but this is not stated explicitly, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_jobs_raw_metadataB
Gets the job raw metadata for the given job IDs passed as parameter.

Args:
    job_ids: List of job IDs to get the job raw metadata for
    
Returns:
    Dict job ids as keys, and the corresponding job metadata information 
    as values (encoded also as a dictonary)
ParametersJSON Schema
NameRequiredDescriptionDefault
job_idsYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'Gets' data, implying a read operation, but doesn't specify if it requires authentication, has rate limits, or what happens with invalid job IDs. This leaves significant behavioral gaps for a tool that fetches metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first followed by parameter and return details. It avoids unnecessary fluff, though the formatting with 'Args:' and 'Returns:' sections is slightly verbose but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (1 parameter, no annotations, no output schema), the description is adequate but incomplete. It covers the basic purpose and parameter semantics but lacks behavioral details like error handling or return format specifics, making it minimally viable but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful context beyond the input schema, which has 0% description coverage. It explains that 'job_ids' is a 'List of job IDs to get the job raw metadata for', clarifying the parameter's purpose and expected format, which compensates well for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Gets') and resource ('job raw metadata'), making it easy to understand what the tool does. However, it doesn't differentiate this tool from its sibling tools like 'get_new_job_ids' or 'get_url_for_jobs_search', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for usage, or comparisons with sibling tools like 'get_new_job_ids' or 'adapt_cv_to_latest_job', leaving the agent without clear usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_new_job_idsA
Gets the new job ids retrieved from the LinkedIn url passed as a parameter, exploring
the number of pages specified.

Args:
    url: The URL to search for jobs in LinkedIn
    num_pages: The number of pages to retrieve ids from
    
Returns:
    A list with the new job IDs retrieved from the explored pages from the URL
ParametersJSON Schema
NameRequiredDescriptionDefault
num_pagesNo
urlYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it describes the core operation (retrieving job IDs from LinkedIn pages), it lacks important behavioral details such as authentication requirements, rate limits, error handling, pagination mechanics, or what constitutes 'new' job IDs. The description is functional but incomplete for a tool that interacts with an external service.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with three clear sections (purpose, args, returns) and front-loaded with the main functionality. The Args and Returns sections are helpful but slightly redundant with the purpose statement. Every sentence contributes value, though minor tightening is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (interacting with LinkedIn, pagination, no output schema, and no annotations), the description is minimally adequate but has significant gaps. It explains what the tool does and its parameters but lacks details about authentication, rate limits, error conditions, return format specifics, or what distinguishes 'new' job IDs. The description meets basic requirements but doesn't fully address the operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining both parameters: 'url' is described as 'The URL to search for jobs in LinkedIn' and 'num_pages' as 'The number of pages to retrieve ids from'. It adds meaningful context beyond the bare schema, though it doesn't specify URL format requirements or page number constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('gets', 'retrieved from', 'exploring') and resources ('new job ids', 'LinkedIn url', 'number of pages'). It distinguishes from siblings by focusing on job ID retrieval rather than CV adaptation, raw metadata fetching, or URL generation for job searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (to get job IDs from LinkedIn URLs with pagination), but doesn't explicitly state when not to use it or name specific alternatives among the sibling tools. The context is sufficient for basic usage decisions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedadapt_cv_to_latest_job
    • First observedget_jobs_raw_metadata
    • First observedget_new_job_ids
    • First observedget_url_for_jobs_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: get_url_for_jobs_search generates search URLs, get_new_job_ids retrieves job IDs from those URLs, get_jobs_raw_metadata fetches metadata for specific jobs, and adapt_cv_to_latest_job adapts a CV to a particular job. There is no overlap in functionality, making tool selection unambiguous.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: get_url_for_jobs_search, get_new_job_ids, get_jobs_raw_metadata, and adapt_cv_to_latest_job. The naming is predictable and readable throughout the set.

Tool Count4/5

With 4 tools, the count is reasonable for a LinkedIn job search and CV adaptation server, covering key workflows from URL generation to CV tailoring. It might be slightly thin for broader LinkedIn operations, but it's well-scoped for its apparent purpose.

Completeness4/5

The tool set covers a complete job search and CV adaptation workflow: generating URLs, retrieving job IDs, fetching metadata, and adapting a CV. A minor gap is the lack of tools for direct LinkedIn profile interactions or job application submission, but the core domain is adequately covered for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches