@thejob/jobs-mcp

Read-only MCP server for thejob-jobs-service.

It exposes published jobs data over stdio so editor agents and other MCP clients can pull current job-market data into drafting and posting workflows without talking to the database directly.

The server is intentionally narrow for the first iteration: it exposes live job search, single-job detail, and similar-job lookup. That is enough to ground social posts, market roundups, and drafting workflows in real data without adding aggregate endpoints yet.

Default target

By default, the published server points at the public production jobs API:

https://thejob-jobs-service-production.up.railway.app

Override it with JOBS_SERVICE_URL if you want to target staging or a local instance instead.

Tools

• jobs_search — search or list published jobs
• jobs_get — fetch one job by shortId
• jobs_similar — fetch jobs similar to one source job

Environment

• JOBS_SERVICE_URL — defaults to https://thejob-jobs-service-production.up.railway.app
• JOBS_SERVICE_API_KEY — optional; forwarded as x-api-key

The server is intentionally read-only. It reuses the jobs service HTTP contract instead of reaching into Mongo directly, so search behavior and projections stay owned by jobs-service.

Install

Run directly with npx:

npx -y @thejob/jobs-mcp

Or install it globally:

npm install -g @thejob/jobs-mcp
thejob-jobs-mcp

Prerequisites

1. Make sure the target jobs service is reachable at JOBS_SERVICE_URL or let the server use the public production API default.
2. If your jobs service requires an API key for the read paths you want to use, set JOBS_SERVICE_API_KEY.

Quick sanity check:

curl -sS 'https://thejob-jobs-service-production.up.railway.app/jobs?limit=1'

For local development against a local jobs service:

JOBS_SERVICE_URL=http://127.0.0.1:3081 npx -y @thejob/jobs-mcp

Build once:

pnpm mcp:build

Typecheck:

pnpm mcp:typecheck

Configure An MCP Client

Repository-local MCP config lives in .mcp.json:

{
	"mcpServers": {
		"thejob-jobs": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@thejob/jobs-mcp"]
		}
	}
}

For local VS Code use, you can create .vscode/mcp.json with the same server definition:

{
	"servers": {
		"thejob-jobs": {
			"command": "npx",
			"args": ["-y", "@thejob/jobs-mcp"]
		}
	}
}

To target a non-default environment, add env:

{
	"mcpServers": {
		"thejob-jobs": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@thejob/jobs-mcp"],
			"env": {
				"JOBS_SERVICE_URL": "http://127.0.0.1:3081"
			}
		}
	}
}

Tool Shapes

• jobs_search
  • Use for live lists, filtered roundups, or keyword-driven post research.
  • Supports mode, search, page, limit, sortBy, sortDirection, and filters.
• jobs_get
  • Use for a richer anchor job when writing a post with concrete role details.
  • Supports shortId, optional fields, and optional includeRawJob.
• jobs_similar
  • Use for expanding one anchor role into a nearby cluster.
  • Supports shortId, pagination, optional filters, and optional includeRawResults.

Typical Content Workflow

1. Call jobs_search to find a live theme, such as AI jobs, remote roles, or one geography.
2. Call jobs_get on one strong anchor role to pull skills, company, description, and apply link.
3. Optionally call jobs_similar to widen the set into a short roundup.
4. Turn the returned jobs into a post, newsletter blurb, or market comment.

Example patterns:

• Find a small live set for a roundup:
  • jobs_search with limit: 5
• Focus on one job for richer copy:
  • jobs_get with shortId: "69MRObfdpPcX"
• Expand an anchor role into adjacent jobs:
  • jobs_similar with shortId: "69MRObfdpPcX", limit: 3

Current Scope

This server does not yet expose trend summaries, top companies, or other custom aggregates. The current goal is simpler: make live job data available to MCP clients so drafting tools can produce richer content grounded in actual jobs.

Publishing

Build and publish from this package directory or via the workspace:

pnpm mcp:build
npm publish --access public

The package exposes the thejob-jobs-mcp binary and is intended to be installed by MCP clients through npx or a global npm install.