mcp-mayo

MCP Server for MAYO Apollo — exposes the HRM platform's Foundation (人事), Attendance (差勤), and Payroll (薪資勞健保) APIs as AI-callable tools via the Model Context Protocol.

繁體中文 · Part of the Asgard AI Platform open-source ecosystem.

Features

• 33 tools — 28 thin wrappers around every MAYO Apollo endpoint plus 5 semantic compositions
• Three backend domains — Foundation, Attendance, Payroll — served from one MCP server with a single hrmlicense API key
• Date-format normalization — callers use ISO YYYY-MM-DD / YYYY-MM; the server converts to each endpoint's expected format internally
• Semantic aggregations — one-call helpers like get_employee_profile, get_organization_snapshot_as_of, get_attendance_summary
• Typed with Pydantic — every parameter has a description the AI can see
• E2E test runner — exercises every registered tool against the live PRE environment

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• A MAYO-issued hrmlicense API key with read access to the FD / PT / PY backends you plan to call

Installation

From source (current state)

git clone https://github.com/asgard-ai-platform/mcp-mayo.git
cd mcp-mayo
uv sync
cp .env.example .env
# Edit .env and set MAYO_API_KEY

From PyPI (once published)

uv add mcp-mayo
# or
pip install mcp-mayo

Configuration

Env var	Required	Purpose
MAYO_API_KEY	Yes	The token value placed on the hrmlicense header; authenticates Foundation, Attendance, and Payroll in a single credential

Usage

Run locally

uv run --env-file .env python mcp_server.py

Claude Desktop

{
  "mcpServers": {
    "mayo": {
      "command": "uvx",
      "args": ["mcp-mayo"],
      "env": {
        "MAYO_API_KEY": "your_hrmlicense_token"
      }
    }
  }
}

Claude Code (.mcp.json)

{
  "mcpServers": {
    "mayo": {
      "command": "uv",
      "args": ["run", "mcp-mayo"],
      "cwd": "${PWD}",
      "env": {
        "PYTHONPATH": "${PWD}",
        "MAYO_API_KEY": "${MAYO_API_KEY}"
      }
    }
  }
}

Cursor / other IDEs

Point the MCP client at uvx mcp-mayo with MAYO_API_KEY in its environment.

Tools

Semantic (recommended for AI use)

Tool	What it does
get_employee_profile	One employee's PA + work history + education in a single call
get_organization_snapshot_as_of	Org tree + active headcount for a date
get_attendance_summary	History + abnormal + overtime + leave fan-out over a range
search_active_employees	list_active_employees with today as default
get_monthly_payroll_report	Single-month salary/bonus roster using ISO YYYY-MM

Foundation (FD) — 15

list_active_employees ¹, list_resigned_employees ¹, get_organization_tree ¹, export_organization_with_employees, export_employees, export_departments, export_organization_full, export_employees_full, export_expatriations, export_working_history, export_education_history, export_employee_changes, export_organization_changes, export_pa_options, export_company_custom_fields

Attendance (PT) — 8

get_attendance_rules, get_attendance_history, get_attendance_abnormal, get_forgot_checkin_records, get_leave_history, get_employee_calendar, get_overtime_records, get_trip_history ²

Payroll (PY) — 5

get_monthly_labor_insurance ², get_monthly_nhi ², get_monthly_labor_pension ², get_salary_insurance_detail, get_salary_bonus_list

¹ The three /ClientOut/ReportCenter/* routes (plus the two semantic wrappers search_active_employees and get_organization_snapshot_as_of that depend on them) currently return 404 on the PRE Foundation backend. The tools stay exposed so they work the moment MAYO redeploys these endpoints.

² Flagged as failing upstream in MAYO's own Postman collection. Same story — tool stays, docstring carries a KNOWN ISSUE note.

Usage Examples

"Who was active in department C030010 yesterday?"

You: 昨天 C030010 部門還在職的人列一下

AI calls:

search_active_employees(
  dept_code = "C030010",
)

Result: SUCCESS — returns the active-employee list from the Foundation backend with today as the effective date.

"Give me A00384's full profile"

You: 給我員編 A00384 的完整資料

AI calls:

get_employee_profile(
  employee_number = "A00384",
)

Result: SUCCESS — aggregates /PA, /Working, and /Education, locally filtered to A00384.

"Attendance picture for the first week of September"

You: 9/1 到 9/7 的出勤統計，含異常跟加班

AI calls:

get_attendance_summary(
  start_date = "2025-09-01",
  end_date   = "2025-09-07",
)

Result: SUCCESS — returns history, abnormal, overtime, and leave sections for the range.

"January salary roster"

You: 2025-01 的薪資發放清冊

AI calls:

get_monthly_payroll_report(
  year_month = "2025-01",
)

Result: SUCCESS — converts to 2025/01 under the hood and calls SalaryBonusList.

Architecture

stdio (JSON-RPC 2.0)
  → mcp_server.py                 entry point; imports tool modules
    → app.py                      FastMCP("mcp-mayo") singleton
      → tools/                    @mcp.tool() decorated functions
          foundation_tools.py       15 FD wrappers
          attendance_tools.py       8 PT wrappers
          payroll_tools.py          5 PY wrappers
          semantic_tools.py         5 high-level compositions
        → connectors/rest_client.py  retry + multi-domain URL resolution
          → auth/api_key.py          builds {"hrmlicense": <MAYO_API_KEY>}
            → config/settings.py     BASE_URLS + ENDPOINTS (keyed by domain)

Testing

uv run --env-file .env python scripts/auth/test_connection.py   # probes FD / PT / PY
uv run --env-file .env python tests/test_all_tools.py           # runs every tool

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.