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, and financial
transactions (summarized), Saudi Nitaqat / Saudization workforce analysis, CHRO-style HR
update metrics, and Performance & Evaluation (P&E) rating distributions.

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?"

6.2 list_branches - List branches

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

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.

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.

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).

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.

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.

First reply (asks you to choose scope):

Final reply (abbreviated):

6.8 get_pe_bell_curve_data - P&E cycles & bell curve

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

  • 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.

  • 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.

7. Companion skills

ZenHR also ships three ready-made skills that teach Claude how to turn the connector's
raw tool output into polished, decision-ready deliverables. You don't have to use them - the
tools work on their own - but the skills add expert structure (which questions to ask first,
how to chart the results, how to present numbers accurately) so you get a board-grade answer
instead of a JSON dump. Just ask Claude in plain language; when your request matches a skill,
it follows that playbook automatically.

7.1 P&E Bell-Curve Analysis

• What it does: turns a Performance & Evaluation cycle into a clear bell-curve report -
  finds the cycle, pulls its rating distribution, renders it as a chart, and compares actual
  vs. your target distribution with a short narrative of the skew.

• Uses: get_pe_bell_curve_data.

• Ask it: "Analyze the bell curve for our 2025 annual review", "How are ratings
  distributed in the Riyadh performance cycle?", "Is our score spread on target?"

• Good to know: it resolves the cycle by name/year first (it won't guess a cycle id),
  quotes every number verbatim from the tool, reports both the scored count and the full
  cohort, and asks for your target distribution rather than inventing one. If you don't give a
  target, it presents the distribution and skew without an "on/off target" verdict.

7.2 Off-Cycle Transactions Analyzer

• What it does: answers questions about off-cycle (out-of-payroll) payments for a branch -
  one-time bonuses, ad-hoc allowances/deductions, quarterly trends, single-employee or
  income-vs-deduction breakdowns - and visualizes them as a year-overview bar chart plus
  per-quarter pies and a table.

• Uses: list_branches and summarize_financial_transactions (always with
  payroll_status: out_of_payroll).

• Ask it: "What off-cycle transactions happened in 2025?", "Show the quarterly off-cycle
  trend for the Amman branch", "Break down off-cycle payments for employee 123 this year",
  "How do off-cycle income and deductions compare for Q3?"

• Good to know: it always confirms the branch and year first (no silent defaults), never
  mixes currencies, and presents results in business language. Because the connector only
  exposes summaries, ranked or single-row lists ("top 10 biggest bonuses", "show the last
  5 transactions") aren't supported - the skill will say so rather than fabricate a ranking.

7.3 CHRO Board Presentation

• What it does: builds a board-ready PowerPoint from live ZenHR HR metrics, filling a
  PowerPoint template you provide with executive-quality slides, native editable charts, and
  an executive narrative.

• Uses: get_hr_updates.

• Ask it: attach a .pptx template and say "Prepare a CHRO board deck for Q2-2026 from
  ZenHR", "Build our H1-2026 people review", "Make a quarterly workforce presentation."

• Good to know: it asks you to confirm scope (all branches vs. one, monthly vs. combined,
  by-department) before pulling numbers, quotes every figure verbatim with period and units,
  labels any metric your role can't see as "not available" instead of estimating, and matches
  your template's branding. (Producing native editable charts requires a PowerPoint/code
  capability in your Claude environment.)

These skills are provided by ZenHR alongside the connector. If they're not already available

in your workspace, ask your ZenHR administrator how to enable them.

8. 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.

9. 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. 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.

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

10. 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.