XHR MCP Server

Python MCP server for X-HR tools. This package is intended to run as a stdio MCP server so external clients can launch it as a local subprocess and communicate through standard input/output.

Transport

This server uses MCP stdio transport.

It is not intended to expose an HTTP MCP endpoint. MCP clients should start the package command directly and let the client manage the stdio session.

Install

From PyPI, once published:

pip install xhr-mcp-server

Or run it without a persistent install:

uvx xhr-mcp-server

For local development:

uv sync

MCP Client Config

Example stdio configuration:

{
  "mcpServers": {
    "xhr": {
      "command": "uvx",
      "args": ["xhr-mcp-server"]
    }
  }
}

If the package is installed in the same environment as the MCP client:

{
  "mcpServers": {
    "xhr": {
      "command": "xhr-mcp-server",
      "args": []
    }
  }
}

Local Development

Run from the repository root:

uv run xhr-mcp-server

The installed package exposes the same command:

xhr-mcp-server

Environment

Common environment variables:

LOG_LEVEL=DEBUG
LOG_FORMAT=pretty
API_BASE_URL=https://api.dev.x-hr.ai
XHR_PAT=

API_BASE_URL defaults to https://api.x-hr.co when unset. For local testing, set it to the dev API URL shown above. XHR_PAT is optional. When present and the MCP request does not include an authorization header, script tools forward it as authorization: Bearer <XHR_PAT>. Script tools also use that authorization header to call /v1/im/me and fill xhr-employee-id and xhr-company-id when they are missing.

Notes

Database migrations, Alembic, SQLAlchemy, and Postgres are intentionally not part of this package.