Skip to main content
Glama
enesjakozh
jhgaylor

HireBase MCP Server

by jhgaylor
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

HireBase MCP Server

A Model Context Protocol (MCP) server providing tools to interact with the HireBase Job API.

License: MIT

Available MCP Interactions

This server exposes the following MCP interactions:

Tools

  • search_jobs: Search for jobs using the HireBase API based on various criteria (keywords, title, location, salary, etc.).

    • Parameters: query, and_keywords, or_keywords, not_keywords, title, category, country, city, location_type, company, salary_from, salary_to, salary_currency, years_from, years_to, visa, limit.

  • get_job: Retrieve detailed information about a specific job using its HireBase ID.

    • Parameters: job_id.

Prompts

  • create_candidate_profile: Generates a structured prompt based on candidate details (name, LinkedIn, website, resume text) to help guide job searching.

    • Parameters: name, linkedin_url, personal_website, resume_text.

Related MCP server: JobDataLake MCP Server

Client Setup (Examples: Claude Desktop, Cursor)

To use this server with an MCP client like Claude Desktop or Cursor, you need to configure the client to run the server process and optionally provide the HireBase API key.

  1. Ensure uv is installed: curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Obtain a HireBase API Key (optional): Request a key from HireBase You can set this as an environment variable (HIREBASE_API_KEY) or just leave it empty.

  3. Configure your client:

    • Using uvx:

      • Claude Desktop: Edit your claude_desktop_config.json:

        {
  "mcpServers": {
    "hirebase": {
      "command": "uvx",
      "args": [
        "hirebase-mcp" 
      ],
      "env": {
        "HIREBASE_API_KEY": "" 
      }
    }
  }
}

      • Cursor: Go to Settings > MCP > Add Server:

        • Mac/Linux Command: uvx hirebase-mcp (Adjust package name if needed)

        • Windows Command: cmd

        • Windows Args: /c, uvx, hirebase-mcp (Adjust package name if needed)

        • Set the HIREBASE_API_KEY environment variable in the appropriate section.

    • Running from source via Python (Alternative):

      1. Clone the repo and note where you clone it to

      2. Claude Desktop: Edit your claude_desktop_config.json:

      {
    "mcpServers": {
        "hirebase": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "--with",
                "requests",
                "mcp",
                "run",
                "PATH_TO_REPO/src/hirebase_mcp/server.py"
            ]
        }
    }
}

Development

This project uses:

  • uv for dependency management and virtual environments

  • ruff for linting and formatting

  • hatch as the build backend

Common Tasks

# Setup virtual env
uv venv

# Install dependencies
uv pip install -e .

# install cli tools
uv tool install ruff

# Run linting
ruff check .

# Format code
ruff format .

Environment Variables

  • HIREBASE_API_KEY (required): Your API key for accessing the HireBase API. The server needs this to make authenticated requests for job data.

Testing

This project uses pytest for testing the core tool logic. Tests mock external API calls using unittest.mock.

  1. Install test dependencies:

# Ensure you are in your activated virtual environment (.venv)
uv pip install -e '.[test]'

  1. Run tests:

# Example command
pytest

Contributing

Contributions are welcome.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

2 tools
get_jobA

Get detailed information about a specific job

Args:
    job_id: The unique identifier of the job
ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes

TDQS

A3.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It mentions 'detailed information' but does not specify what fields are returned, any authentication or rate limits, or confirm it is a read-only operation. The description lacks sufficient behavioral context.

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

Conciseness5/5

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

The description is two short sentences with a structured Args section, no redundant words, and perfectly sized for the tool's simplicity.

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?

For a simple single-parameter get tool, the description is adequate but could be improved by noting what 'detailed information' includes, potential error conditions, or expected return format. Without annotations or output schema, additional context would enhance completeness.

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 coverage, the description compensates by adding meaning: 'job_id: The unique identifier of the job' goes beyond the schema's title 'Job Id', explaining the parameter's role effectively.

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 verb 'get' and the resource 'detailed information about a specific job', and the sibling tool 'search_jobs' implies this tool is for fetching a single job by ID, distinguishing it effectively.

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

Usage Guidelines3/5

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

The description implies usage for fetching a specific job by ID, but provides no explicit guidance on when to use it versus the sibling 'search_jobs', nor any exclusions or prerequisites.

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

search_jobsB

Search for jobs using the HireBase API

Args:
    query: Full text search query
    and_keywords: Keywords that must all appear in results
    or_keywords: Keywords where at least one must appear
    not_keywords: Keywords that must not appear
    title: Job titles to search for
    category: Job categories to filter by
    country: Countries to filter by
    city: Cities to filter by
    location_type: Location types (Remote, In-Person, Hybrid)
    company: Companies to filter by
    salary_from: Minimum salary
    salary_to: Maximum salary
    salary_currency: Salary currency (e.g. USD)
    years_from: Minimum years of experience
    years_to: Maximum years of experience
    visa: Whether job offers visa sponsorship
    limit: Maximum number of results to return
ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
and_keywordsNo
or_keywordsNo
not_keywordsNo
titleNo
categoryNo
countryNo
cityNo
location_typeNo
companyNo
salary_fromNo
salary_toNo
salary_currencyNo
years_fromNo
years_toNo
visaNo
limitNo

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, and the description lacks behavioral context such as read-only status, pagination behavior, rate limits, or cost implications. The parameter 'limit' hints at pagination but doesn't explain default or maximum results. The tool's safety profile (e.g. destructive or not) is completely unspecified.

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 relatively concise, starting with a clear one-line summary followed by a bulleted list of parameters. It avoids unnecessary prose. However, the parameter list could be streamlined further, and the formatting is slightly inconsistent (e.g., some descriptions end with periods, others do not).

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 tool has 17 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what the return format is, how pagination works, or any side effects. The agent lacks essential runtime information for a complex search tool.

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?

With 0% schema description coverage, the description partially compensates by providing brief explanations for each parameter (e.g., 'Full text search query', 'Keywords that must all appear'). However, these descriptions are often repetitive of the parameter titles and lack additional detail like allowed values or formatting. They add value but not enough to fully overcome the coverage gap.

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 'Search for jobs' using a specific API. It identifies the verb (search), the resource (jobs), and the system (HireBase API). The sibling tool 'get_job' likely retrieves a single job, making this tool's purpose distinct for broad search/filtering.

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

Usage Guidelines3/5

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

No explicit when-to-use or alternative guidance is provided. The description only lists parameters, leaving the agent to infer usage context. The sibling 'get_job' implies a distinction between search and retrieval, but no direct comparison or exclusion criteria are given.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one retrieves a single job by ID, the other searches/filters jobs. There is no overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent snake_case verb_noun pattern (get_job, search_jobs), making them predictable and easy to understand.

Tool Count3/5

With only 2 tools, the server feels minimal for a job platform. While it covers basic search and retrieval, the scope is thin and suggests missing functionality like listing or management tools.

Completeness3/5

The tool set covers searching and fetching job details but lacks listing all jobs, CRUD operations, or endpoints for related entities like categories or companies. This leaves notable gaps for a full-featured job interface.

Maintenance

ActivityInactive
ResponsivenessSyncing

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

  • Adzuna Jobs MCP Server

    folathecoder
    A
    license
    A
    quality
    D
    maintenance
    Provides AI assistants with access to the Adzuna Job Search API to search millions of job listings, analyze salary data, and research top employers across 12 countries with comprehensive filtering options.
    7
    15
    MIT

  • JobDataLake MCP Server

    echojobsio
    A
    license
    A
    quality
    B
    maintenance
    Enables searching over 1 million enriched job listings from 20,000+ companies directly from MCP-compatible AI tools. Provides tools for job search, company profiles, and AI-powered similar job recommendations with real-time data updates.
    4
    73
    2
    MIT

  • recruiting-jobs-mcp

    emily397
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to pull live job listings from major ATS platforms (Greenhouse, Lever, Ashby, Workable), Hacker News hiring threads, and detect hiring signals on company career pages.

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jhgaylor/hirebase-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server