Jobswithgpt MCP Server: Job Search 500K+ Listings

Overview

The Jobswithgpt MCP Server is a Model Context Protocol (MCP)–compatible service that indexes and serves over 500,000 public job listings. It provides a structured, searchable API to fetch up-to-date job data suitable for integration with LLMs, chatbots, job boards, analytics pipelines, and other developer tools that need reliable employment market context.

Because listings are refreshed continuously, clients receive recent postings and can rely on near-real-time results for conversational assistants, candidate discovery, or data analysis. The server exposes simple REST endpoints and MCP tool/resource descriptors so AI agents and external apps can discover capabilities programmatically.

Features

• MCP-compatible tool and resource descriptors for model-driven integrations
• Search across 500K+ public job listings with continuous refresh
• Full-text and faceted search (title, company, location, remote, tags)
• Pagination, sorting, and basic relevance scoring
• Standard JSON REST API with CORS support
• Docker-friendly and scalable deployment
• Optional API key or token-based access control
• Export and webhook hooks for downstream workflows

Installation / Configuration

Below are common ways to run the server: Docker (recommended for production) and local development.

Prerequisites:

• Docker & Docker Compose (or Node/Python runtime for local)
• A PostgreSQL or compatible database for indexing (optional: local SQLite for dev)
• Environment variables (see sample .env)

Example .env (replace values as needed):

PORT=8080
DATABASE_URL=postgres://user:pass@db:5432/jobs
API_KEY=replace-with-secret
DATA_REFRESH_CRON="*/10 * * * *" # every 10 minutes
LOG_LEVEL=info
CORS_ALLOWED_ORIGINS=*

Docker Compose (example):

version: '3.8'
services:
  mcp-server:
    image: jobswithgpt/mcp:latest
    ports:
      - "8080:8080"
    env_file:
      - .env
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: jobs
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:

Run:

docker-compose up -d
# check logs
docker-compose logs -f mcp-server

Local development (Node-style example):

git clone https://github.com/jobswithgpt/mcp.git
cd mcp
npm install
cp .env.example .env          # edit .env values
npm run dev                  # or `npm start` for production

Available Resources

The server exposes common endpoints for discovery and job access. Exact paths may vary by release; these are the canonical endpoints developers can expect.

Query parameters for /v1/jobs:

• q — free-text query (title, skills)
• location — city, region, or country
• remote — true/false
• company — company name filter
• tags — comma-separated tag list
• page — page number (default 1)
• per_page — items per page (default 20, max typically 100)
• sort — relevance, date_desc, date_asc

Sample /v1/jobs response schema (JSON object):

{
  "total": 523412,
  "page": 1,
  "per_page": 10,
  "results": [
    {
      "id": "abcd1234",
      "title": "Machine Learning Engineer",
      "company": "Acme AI",
      "location": "Remote",
      "remote": true,
      "url": "https://acme.ai/jobs/123",
      "description": "Short description or excerpt",
      "date_posted": "2026-03-28T12:00:00Z",
      "source": "public_feed",
      "tags": ["ml", "python", "remote"],
      "score": 0.87
    }
  ]
}

Use Cases

1. LLM-assisted job search

   • Integrate the MCP descriptors into an assistant so it can call /v1/jobs to fetch current listings, then summarize or rank results for a conversational user.

2. Job board or UI

   • Power a client-facing search widget with filters (location, remote, tags) backed by the MCP server. Use pagination and sorting to navigate large result sets.

3. Recruiting and sourcing

   • Automate discovery by querying for role-specific