Career Intelligence MCP

An AI-powered career intelligence platform for job seekers. Parse resumes, scrape and score job listings, analyze skill gaps, and prepare for interviews.

Features

• Resume Parsing — Paste your resume text, get structured data (name, skills, experience, education)
• Resume Improvement — Get AI suggestions to strengthen your resume for a target role
• Job Scraping — Paste any job listing URL (LinkedIn, Indeed, Glassdoor, etc.) and get structured data
• Job Scoring — Compare multiple jobs against your resume and see match scores
• Job Comparison — Side-by-side comparison of 2-3 jobs (salary, skills, risks, recommendation)
• Skill Gap Analysis — Identify missing skills for a target role with a learning roadmap
• Career Path — Get a career progression plan based on your resume
• Salary Estimation — Estimate salary ranges based on skills, experience, and location
• Interview Questions — Generate technical, behavioral, and follow-up questions for any role
• Market Analysis — Analyze hiring trends and skill demand

Requirements

• Python 3.12+
• An OpenRouter API key (free tier works)

Setup

1. Clone and install dependencies

git clone <your-repo-url>
cd mcp-intel
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

2. Configure environment

cp .env.example .env
# Edit .env with your settings:
# LLM_API_KEY=your_openrouter_api_key
# DATABASE_URL is already set to use SQLite (career_intel.db)

3. Get an OpenRouter API key

1. Sign up at openrouter.ai
2. Go to Keys → Create key
3. Add to .env as LLM_API_KEY=sk-or-...

Default model is deepseek/deepseek-chat (free tier, works well). You can change LLM_MODEL in .env to any OpenRouter model.

4. Run the app

python -m app.main
# Database (career_intel.db) auto-creates on first run

That's it — no database setup needed. The SQLite file (career_intel.db) is created automatically.

---

Deployment Options

Choose the option that fits your setup.

Option 1: Local HTTP Server (Development)

The server runs as an HTTP server on localhost:8000. Connect to it using any HTTP-capable MCP client.

python -m app.main
# Server starts on http://0.0.0.0:8000

---

Option 2: Stdio Mode (Direct MCP Connection)

Run as a stdio MCP server. This connects directly to an MCP client like Claude Desktop without needing HTTP.

python -m app.main --transport stdio

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "career-intel": {
      "command": "/full/path/to/venv/bin/python",
      "args": ["-m", "app.main", "--transport", "stdio"]
    }
  }
}

Setup steps:

1. Run the server in stdio mode or use Claude Desktop config above
2. Restart Claude Desktop

---

Option 3: Cloudflare Tunnel (Remote Access)

Expose your locally-running server to the internet securely using Cloudflare Tunnel — no public IP, account, or firewall needed.

Step 1: Install cloudflared

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

Step 2: Start the app

python -m app.main

Step 3: Start the tunnel

cloudflared access --url http://localhost:8000
# You'll see output like:
# Your tunnel Qo7xG@example.app.link

Step 4: Connect Claude Desktop

{
  "mcpServers": {
    "career-intel": {
      "command": "cloudflared",
      "args": ["access", "--url", "http://localhost:8000"]
    }
  }
}

Setup steps:

1. Install cloudflared
2. Start the app (python -m app.main)
3. Start cloudflared tunnel
4. Add to Claude Desktop config
5. Restart Claude Desktop

---

Option 4: ngrok Tunnel (Remote Access)

Expose your locally-running server via ngrok. Requires an ngrok account (free tier works).

Step 1: Install ngrok

# macOS
brew install ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

Step 2: Sign up and get your authtoken

1. Sign up at ngrok.com
2. Copy your authtoken from the dashboard
3. Configure it: ngrok config add-authtoken YOUR_TOKEN

Step 3: Start the app

python -m app.main

Step 4: Start ngrok

ngrok http 8000
# You'll see output like:
# Forwarding  https://abc123.ngrok.io -> http://localhost:8000

Step 5: Connect Claude Desktop

{
  "mcpServers": {
    "career-intel": {
      "command": "ngrok",
      "args": ["http", "--domain", "your-ngrok-subdomain.ngrok.io", "8000"]
    }
  }
}

Setup steps:

1. Install ngrok and create an account
2. Add your authtoken: ngrok config add-authtoken YOUR_TOKEN
3. Start the app (python -m app.main)
4. Start ngrok (ngrok http 8000)
5. Add to Claude Desktop config
6. Restart Claude Desktop

---

Connecting to Claude Desktop

After setting up your preferred deployment option, add to Claude Desktop:

{
  "mcpServers": {
    "career-intel": {
      "command": "/full/path/to/venv/bin/python",
      "args": ["-m", "app.main", "--transport", "stdio"]
    }
  }
}

Or if using a tunnel (cloudflared or ngrok):

{
  "mcpServers": {
    "career-intel": {
      "command": "cloudflared",
      "args": ["access", "--url", "http://localhost:8000"]
    }
  }
}

Then restart Claude Desktop.

---

Usage Examples

Parse your resume

User: Parse my resume:
[Full resume text pasted here]

Assistant calls: parse_resume(raw_text="...")
Returns: { name, email, skills, experience, education, ... }

Scrape a job listing

User: Scrape this job: https://www.linkedin.com/jobs/view/12345

Assistant calls: scrape_job_listing(url="...")
Returns: { title, company, location, description, salary_min, salary_max, ... }

Score jobs against your resume

User: Score these jobs for me [paste resume] [paste job URLs]

Assistant calls:
1. scrape_job_listing(url="...") — for each URL
2. score_jobs_for_candidate(resume_text="...", jobs=[...])
Returns: [{ job, score (0-100), match_reasons, weaknesses }, ...]

Compare jobs

User: Compare these 2 jobs [paste job details]

Assistant calls: compare_jobs(jobs=[...])
Returns: { strengths, risks, salary_comparison, skill_overlap, overall_recommendation }

Prepare for interviews

User: Generate interview questions for this job [paste job description]

Assistant calls: generate_interview_questions(job_description="...")
Returns: { technical: [...], behavioral: [...], follow_up: [...] }

Analyze skill gaps

User: What skills am I missing for a Staff Engineer role? [paste resume]

Assistant calls: skill_gap_analysis(resume_text="...", target_role="Staff Engineer")
Returns: { current_skills, missing_skills, roadmap: [{ skill, resources, timeline, priority }] }

---

Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./career_intel.db	SQLite database path
LLM_API_KEY	(empty)	OpenRouter API key
LLM_MODEL	deepseek/deepseek-chat	OpenRouter model to use
LLM_BASE_URL	https://openrouter.ai/api/v1	OpenRouter base URL
LOG_LEVEL	INFO	Logging level

---

API Endpoints

• GET /health — Health check. Returns database and LLM status.

---

Architecture

• FastMCP — Server framework
• SQLAlchemy (async) — Database ORM
• SQLite — Local database (no server setup)
• OpenRouter — LLM calls (DeepSeek, Claude, etc.)
• httpx + BeautifulSoup — Job listing scraping