LinkedIn MCP Server
Enables Claude to access and analyze LinkedIn profile data through the Model Context Protocol, allowing users to query their LinkedIn information directly within Claude Desktop.
README Documentation
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
- Job Querying — Composable filters (company, location, keywords, remote, visa, posted date)
- Live Exploration — On-demand scraping for 1-10 most recent jobs
- Profile Management — Add/update/delete autonomous scraping profiles
- Application Tracking — Track application status and notes
- Company Enrichment — Automatic company metadata lookup
- Job Change Detection — Audit log for field changes over time
- Analytics — Database statistics and scraping profile health
Prerequisites
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.