ZenHR Connector for Claude: Accessing HR Data and Insights

1. Overview

Ask Claude about your workforce - ZenHR HR, payroll, compliance, and performance data- read-only.

The ZenHR Connector lets you bring your live ZenHR data into Claude so you can ask questions in plain language and get answers grounded in your own HR system. It exposes a small, curated set of read-only tools covering your employee directory, branches, financial transactions (summarized), Saudi Nitaqat / Saudization workforce analysis, CHRO-style HR update metrics, Performance & Evaluation (P&E) rating distributions, and team time-off/vacation planning. 

ZenHR is a comprehensive HR and payroll platform for businesses across the MENA region. This connector is built and operated by ZenHR. It runs through ZenHR's standard sign-in and permission system, so Claude only ever sees the data you are already allowed to see in ZenHR - and it can never change, add, or delete anything. Every connection is isolated to your company. 

2. What you can ask

Example prompts and the tools they use:

3. Prerequisites

·       An active ZenHR account.

·       Your access is governed by your ZenHR role. The connector returns only data your role can already read in ZenHR. If your role can't see a certain area (e.g., financial
 transactions), Claude won't be able to either.

·       The Nitaqat tools are specific to Saudi Arabia (KSA).

4. Installation & connection

You add the connector in Claude as a custom connector pointing at your ZenHR endpoint.

1.     In Claude, go to Settings → Connectors → Add custom connector.

2.     Enter the Server URL: https://app.zenhr.com/zen_mcp

3.     Claude automatically discovers how to sign you in.

4.     Claude opens the ZenHR sign-in and consent screen. Sign in with your ZenHR account and approve the read-only permissions listed in §5. There's no password or secret to copy - the connection uses a secure OAuth flow.

5.     Once you approve, Claude connects, and the connector's tools become available. You're ready to ask questions.

Your session can be ended at any time by disconnecting the connector in Claude.

5. Authentication & permissions

·       Sign-in method: OAuth 2.1 with PKCE - the same secure, browser-based sign-in flow used across ZenHR. No client secret, no API key to manage. Sessions refresh automatically.

·       Where you sign in: ZenHR's own authorization server. Claude discovers it via standard OAuth metadata and registers itself automatically before the first sign-in.

·       Per-company isolation: your connection is tied to your ZenHR user within your company. Data never crosses company boundaries.

6. Tools

All tools are read-only - none of them changes, creates, or deletes data. Most list-style tools accept page and limit for paging and an optional exclude_fields list to leave out fields you don't need (which also keeps responses smaller). Tools draw on your live ZenHR data through ZenHR's API, honoring your role's permissions on every call.

6.1 get_my_profile - My profile

·       Read-only. Returns your signed-in profile, authentication info, and token/expiry status.

·       Parameters: none.

·       Use it for: "Who am I signed in as?", "Is my session still valid?"

{ "method": "tools/call", "params": { "name": "get_my_profile", "arguments": {} } }

{ "structuredContent": {

    "user_id": 90210, "employee_id": 33412, "name": "Sample User",

    "company_id": 771, "branch_id": 4821,

    "token_expires_at": "2026-06-23T18:40:00Z" } }

6.2 list_branches - List branches

·       Read-only. Lists the branches you can access. Useful for finding branch IDs to pass to other tools.

{ "method": "tools/call", "params": { "name": "list_branches",

  "arguments": { "country_id": 134, "limit": 5 } } }

{ "structuredContent": {

    "branches": [

      { "id": 4821, "name": "Riyadh HQ", "country": { "country_code": "SA" } },

      { "id": 4822, "name": "Jeddah Office", "country": { "country_code": "SA" } } ],

    "pagination": { "page": 1, "total_pages": 1, "total": 2 },

    "search_term": null } }

6.3 list_employees - List employees

·       Read-only. Lists employees in a branch (defaults to your current branch).

·       Tip: employee records can include personal fields (e.g. passport number, national ID, religion, contact details). If you only need basic fields, pass exclude_fields to leave the rest out.

{ "method": "tools/call", "params": { "name": "list_employees",

  "arguments": { "branch_id": 4821, "limit": 2,

    "exclude_fields": ["passport_number", "national_id", "religion"] } } }

{ "structuredContent": {

    "employees": [

      { "id": 33412, "name": "Sample Employee A", "employment_number": "E-1001",

        "nationality": ["Saudi Arabia"] },

      { "id": 33413, "name": "Sample Employee B", "employment_number": "E-1002",

        "nationality": ["Jordan"] } ],

    "pagination": { "page": 1, "total_pages": 18, "total": 36 },

    "branch_id": 4821, "search_term": null } }

6.4 summarize_financial_transactions - Summarize financial transactions

·       Read-only. Aggregates a branch's financial transactions by currency → quarter →
 transaction type, returning counts, total amounts, and percentages. It pages through the data for you, so you don't pass page/limit.

·       Note: it reads up to 1,500 transactions per request (30 pages × 50). If there are more, the response sets truncated: true so you know the totals are partial - narrow the date window or filters to get a complete picture.

{ "method": "tools/call", "params": { "name": "summarize_financial_transactions",

  "arguments": { "branch_id": 4821, "direction": "deduction",

    "effective_date_from": "2026-01-01", "effective_date_to": "2026-06-30" } } }

{ "structuredContent": {

    "summary": { "total_transactions": 84, "dropped_transactions": 0,

      "pages_fetched": 2, "total_pages": 2, "branch_id": 4821, "truncated": false,

      "window": { "from": "2026-01-01", "to": "2026-06-30" },

      "filters": { "direction": "deduction" } },

    "currencies": [

      { "currency": "SAR", "count": 84, "amount_fils": 12500000,

        "quarters": [

          { "quarter": "Q1 2026", "count": 40, "amount_fils": 6000000,

            "percentage_of_currency_total": 48.0,

            "types": [ { "name": "GOSI Deduction", "count": 40, "amount_fils": 6000000,

              "percentage_of_quarter": 100.0, "percentage_of_currency_total": 48.0 } ] } ] } ] } }

6.5 get_nitaqat_workforce - KSA workforce data

·       Read-only. Returns active-employee counts and a Saudi vs. non-Saudi breakdown per KSA branch, for Saudization / Nitaqat analysis. (An employee counts as Saudi when their nationality includes "Saudi Arabia".)

·       It does not compute your Nitaqat range itself - pair it with get_nitaqat_guideline, which provides the official formulas so the range can be calculated.

·       Note: economic_activity is required. If you don't know it, ask get_nitaqat_guideline for the valid activities in Annex No. (1).

{ "method": "tools/call", "params": { "name": "get_nitaqat_workforce",

  "arguments": { "economic_activity": "Manufacturing" } } }

{ "structuredContent": {

    "economic_activity": "Manufacturing", "country_code": "SA",

    "nitaqat_official_source_url": "https://www.hrsd.gov.sa/.../E20210523.pdf",

    "nitaqat_resource_uri": "zenhr://compliance/nitaqat",

    "summary": { "ksa_branch_count": 2, "total_active_employees": 120,

      "total_saudi_employees": 78, "total_non_saudi_employees": 42,

      "saudization_rate_percent": 65.0 },

    "branch_breakdown": [

      { "id": 4821, "name": "Riyadh HQ", "country_code": "SA",

        "total_active_employees": 80, "total_saudi_employees": 56,

        "total_non_saudi_employees": 24, "saudization_rate_percent": 70.0 } ] } }

6.6 get_nitaqat_guideline - Nitaqat guideline

·       Read-only. Returns the Nitaqat Mutawar Program guideline (v2.0) - Annex No. (1)
 economic activities, the m/c coefficients, the range formulas (y = m · ln(x) + c), and the ministry services by range color - sourced from the official HRSD document.

·       Parameters: none.

·       Use it for: understanding Nitaqat rules, and (with get_nitaqat_workforce) working out your range.

{ "method": "tools/call", "params": { "name": "get_nitaqat_guideline", "arguments": {} } }

6.7 get_hr_updates - HR updates

·       Read-only. Computes company HR metrics for a quarter, half, or full year - for CHRO board decks and workforce reviews. Metrics include headcount (start/end/net), new hires, separations, turnover (overall/voluntary/involuntary/first-year), retention, disciplinary-action rate, and gender breakdown.

·       This is a two-step tool. Call it with just period first; it replies with the choices to confirm (all branches vs. a specific branch; per-branch breakdown; monthly vs. combined; by-department for a specific branch). Then call it again with your selections.

·       Note: per-branch breakdown is capped at 30 branches; if you can access more, pick a specific branch or use the company total. Metrics your role can't read are listed under unavailable rather than returned.

{ "method": "tools/call", "params": { "name": "get_hr_updates",

  "arguments": { "period": "Q2-2026" } } }

First reply (asks you to choose scope):

{ "structuredContent": { "status": "needs_selection",

    "missing": ["branch_scope"], "errors": [] } }

Final reply (abbreviated):

{ "structuredContent": {

    "period": { "label": "Q2 2026" },

    "grouping": { "branch": "all", "time": "combined", "org": "combined" },

    "metrics_included": ["headcount_end_of_period", "new_hires", "overall_turnover_rate"],

    "segments": [ { "segment": "Company", "dimension": "company",

      "buckets": [ { "label": "Q2 2026",

        "metrics": { "new_hires": { "label": "New hires", "value": 12, "unit": "employees" } } } ] } ],

    "unavailable": {} } }

6.8 get_pe_bell_curve_data - P&E cycles & bell curve

·       Read-only. Performance & Evaluation analysis, with two modes:

o   Discovery - call it without evaluation_cycle_id to list the evaluation cycles you can access (optionally filtered by year) and find the one to analyze.

o   Bell curve - call it with evaluation_cycle_id to get that cycle's rating distribution (per scale band) and summary statistics, across every branch the cycle spans that you can access.

{ "method": "tools/call", "params": { "name": "get_pe_bell_curve_data",

  "arguments": { "evaluation_cycle_id": 512, "score_type": "final" } } }

{ "structuredContent": {

    "meta": { "evaluation_cycle_id": 512, "evaluation_cycle_name": "2025 Annual",

      "year": 2025, "score_type": "final", "total_with_scores": 96, "total_in_cohort": 100,

      "branches_included": [ { "id": 4821, "name": "Riyadh HQ" } ] },

    "distribution_by_scale": [

      { "level": 1, "name": "Below Expectations", "count": 6, "percentage": 6.25 },

      { "level": 2, "name": "Meets Expectations", "count": 70, "percentage": 72.92 },

      { "level": 3, "name": "Exceeds Expectations", "count": 20, "percentage": 20.83 } ],

    "statistics": { "mean": 78.4, "median": 79.0, "std_dev": 8.1, "min": 55.0, "max": 96.0 } } }

6.9 get_team_timeoff - Team time-off/vacation planning

·       Read-only. Lists team time-off (leave) entries that overlap a date window - any leave whose dates intersect the window is returned. Built for vacation planning: "who's off next week?", "how many leave days did X take this month?", or checking team availability before scheduling new time off. It does not submit, approve, or reject requests.

·       Parameters:

o   from_date (required, ISO 8601 e.g. 2026-07-01) - start of the date window.

o   to_date (optional, ISO 8601) - end of the window. Defaults to 6 days after
 from_date (one week).

o   branch_id (optional) - branch to query; defaults to your current branch. Ignored when
 company_wide: true.

o   employee_id (optional) - filter to a single employee (use for "how many leaves did X
 take?").

o   status (optional) - approved (default; confirmed leaves, including HR-entered),
 pending (awaiting approval), or all.

o   company_wide (optional, default false) - when true, queries all accessible
 branches (matches the dashboard "who is off" view); when false, queries the current
 branch only.

·       Note: results are capped at 200 entries (across up to 50 branches). When more exist, the response sets truncated: true - narrow the date range or filter by employee_id for complete data.

{ "method": "tools/call", "params": { "name": "get_team_timeoff",

  "arguments": { "from_date": "2026-07-06", "to_date": "2026-07-12",

    "company_wide": true, "status": "approved" } } }

{ "structuredContent": {

    "timeoff_entries": [

      { "id": 55101, "employee_id": 33412, "employee_name": "Sample Employee A",

        "timeoff_type": "Annual Leave", "from_date": "2026-07-06", "to_date": "2026-07-10",

        "amount_days": 5, "status": 2 },

      { "id": 55102, "employee_id": 33413, "employee_name": "Sample Employee B",

        "timeoff_type": "Sick Leave", "from_date": "2026-07-08", "to_date": "2026-07-09",

        "amount_days": 2, "status": 2 } ],

    "date_range": { "from": "2026-07-06", "to": "2026-07-12" },

    "total_entries": 2, "truncated": false,

    "filters": { "status": "approved", "company_wide": true } } }

7. Security

·       Your data stays yours: every request is tied to your verified ZenHR sign-in and your
 company; data never crosses company boundaries.

·       Read-only by design: connector sessions run under a permission set that is locked to read-only access. Even if your ZenHR role has edit rights, the connector cannot use them - it strips everything down to reading the allow-listed areas.

·       Your role still applies: on every call, the connector checks what your role can read, so you never see more through Claude than you would in ZenHR.

·       Rate limits: requests are limited per company (by default 100/hour and 500/day) to protect the service.

·       Secure transport & sign-in: served over HTTPS using OAuth 2.1 with PKCE; there are no long-lived secrets to manage.

·       Company-level availability: the connector is enabled per company and is otherwise
 unreachable.

8. Limitations & things to know

1.     Read-only: the connector cannot create, edit, or delete anything in ZenHR.

2.     list_employees includes personal fields by default - pass exclude_fields to omit
 what you don't need.

3.     Financial summaries can be partial for very large date ranges: summarize_financial_transactions
 reads up to ~1,500 transactions and sets truncated: true when there's more. Narrow the
 window or filters for complete totals.

4.     get_hr_updates is a two-step tool and caps per-branch breakdowns at 30 branches.

5.     get_nitaqat_workforce requires economic_activity (from Annex No. (1)).

6.     get_team_timeoff is an overlap query (any leave intersecting the window) and is capped
 at 200 entries across up to 50 branches - it sets truncated: true when there's more. It
 queries your current branch unless you pass company_wide: true for the all-branches view.

7.     Permissions are all-or-nothing at connect time: you approve the full read-only
 permission set once; your ZenHR role then governs what's actually visible per area.

8.     Availability is gated per company, and the connector is currently pre-GA (being rolled out company by company).

9. Troubleshooting / FAQ

·       Claude can't reach the connector/everything returns "not found" → the connector isn't enabled for your company yet. Ask your ZenHR administrator to enable it.

·       You keep getting asked to sign in, or see "Unauthorized" → re-run the sign-in/consent so all read-only permissions are granted; your session may have expired.

·       "You are not authorized to do that" → your ZenHR role can't read that area, or you've hit the rate limit (100/hour or 500/day per company).

·       "No branch available" → pass a branch_id, or make sure your account is linked to a
 branch. Use list_branches to find IDs.

·       get_nitaqat_workforce keeps asking for the economic activity → it's required; ask
 get_nitaqat_guideline for the valid Annex No. (1) activities.

·       get_hr_updates replies with needs_selection / needs_narrowing → it's the two-step flow: provide the requested choices and call again; pick one branch if you can access more
 than 30.

·       Some HR metrics show as "unavailable" → those metrics aren't permitted for your role.