jisr-mcp
This server provides read-only Jisr HR operations and metadata tools over MCP.
Check connection health:
jisr_connection_status_getreports reachability, last authentication, and the last auth error.Explain capabilities:
jisr_capabilities_getlists every documented Jisr operation and why each is or isn't available to the current caller.Browse reference data: list departments, employment types, business units, locations, nationalities, and outsourcing companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies. companies.
Inspect integration configuration: list webhook subscriptions and audit events.
Get the data catalog:
jisr_data_catalog_getdescribes domains, tools, classified field groups, pagination, and data freshness.
All exposed tools are read-only; no writes, employee records, or financial records appear in this schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jisr-mcp list employees who joined in the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
jisr-mcp
An MCP server that exposes the documented Jisr HR Open API to any MCP client — Claude Code, Claude Desktop, Cursor, Codex, and anything else that speaks the protocol.
Unofficial. Not affiliated with, endorsed by, or supported by Jisr. It uses only Jisr's publicly documented Open API, and never scrapes the web application or calls undocumented endpoints.
Status: in development. Not yet published to npm. Picking this up? Start with HANDOFF.md — current state, what is blocked, and what to do next. The specification, plan and task breakdown live in
specs/001-jisr-mcp-server/.
What it does
Covers all 20 documented Jisr read operations — employees, attendance, leave, accruals, payroll and finance, accounting journals, all six lookups, webhooks and audit events — plus three discovery tools, as 23 purpose-built read tools. Feature 002 adds three controlled writes as prepare/commit tool pairs (six tools), every one disabled by default.
There is no generic HTTP tool and no way to reach an operation outside the documented surface. It runs against live Jisr data: no database, no queue, no background workers.
Controlled writes (disabled by default)
Every write is a prepare/commit pair: *_prepare validates and previews without touching
Jisr and returns a single-use confirmation reference (5-minute validity); *_commit takes only
that reference and performs exactly the previewed write, then reports the state re-read from
Jisr — never an echo of what was sent. A write domain that is not explicitly enabled is
absent: its tools do not appear in tools/list for any profile.
Pair | Flag | Profile | Notes |
|
|
| Single punch; current or previous calendar month only; reason required |
|
|
| Live lookup resolution; duplicate warning must be acknowledged |
|
|
| Destructive and dormant; also requires the finance surface; target re-validated at commit |
Do not enable any write flag before its section in
docs/write-contract-verification.md carries live
verification evidence.
Related MCP server: FileMaker MCP Server
Prerequisites
Node.js 20 or newer.
A Jisr organization with Open API access, and an administrator who can create API credentials under Settings → Webhook & API Keys → API Keys → Add New API Key.
Nothing else. If you find yourself installing a database, that's a bug.
The secret is shown once. If it isn't captured at creation, create a new key.
Create two keys, not one
Key | Permissions | Used for |
| Core HR read only | Everyday operation |
Finance key (optional) | Adds Get Employee Financial Info | Only if you enable the finance surface |
This is not ceremony. Jisr returns basic_salary, first_salary_pay_date and
last_salary_pay_date inside the ordinary employee list whenever the connected key holds
finance permission — governed by the key, not by who is asking. This server strips those fields for
non-finance callers, but a narrow key means they never cross the network at all.
Configuration
JISR_BASE_URL=https://apis.jisr.net/api # AWS-hosted
# JISR_BASE_URL=https://api.jisr.net.sa/api/ # locally hosted
JISR_SLUG=your-organization-slug
JISR_API_KEY=...
JISR_API_SECRET=...
JISR_ROLE_PROFILE=hr_operationsWhich base URL? If your Jisr web address ends in .jisr.net.sa you are locally hosted;
otherwise AWS. Any other host is rejected at startup.
Role profiles: employee_self, manager, hr_operations, finance, integration_admin,
auditor, platform_operator. The profile decides which tools you see and which records they
return.
employee_self and manager are defined relative to a person, so they also need
JISR_SUBJECT_EMPLOYEE_ID set to that employee's Jisr UUID. The server refuses to start without
it rather than returning nothing and letting it look like the person manages nobody.
See docs/authorization-matrix.md for exactly which tools each
profile gets, and which records.
Enabling the finance surface
The six financial tools — employee financial information, monthly payables, payroll transactions, GL transaction types, paygroups and accounting journals — require two independent conditions:
JISR_ROLE_PROFILE=finance, andJISR_FINANCE_SURFACE=enabled
Either alone is insufficient, and that is deliberate. If key permission alone were enough, the first operator to create one convenient broad key would expose payroll to every agent connected to it. With the surface disabled the tools do not appear in the tool list at all — a non-finance caller cannot discover that payroll tooling exists.
JISR_FINANCE_SURFACE=enabled
JISR_FINANCE_API_KEY=... # recommended: the separate finance-scoped key
JISR_FINANCE_API_SECRET=...Without this, the six financial tools do not appear — even if your Jisr key permits them. Key permission alone is deliberately not sufficient.
Client setup
Configuration formats differ per client. Use the block for yours.
Claude Code
# Project scope — shared with your team via .mcp.json
claude mcp add jisr --scope project \
--env JISR_BASE_URL=https://apis.jisr.net/api \
--env JISR_SLUG=your-organization-slug \
--env JISR_API_KEY=... \
--env JISR_API_SECRET=... \
--env JISR_ROLE_PROFILE=hr_operations \
-- npx -y jisr-mcp
# User scope — available in all your projects, config kept outside the repo
claude mcp add jisr --scope user --env ... -- npx -y jisr-mcpVerify with claude mcp list.
Project scope writes credentials into
.mcp.json, which is committed. Prefer--scope user, or use project scope only with${VAR}references rather than literal secrets.
Cursor
Project-scoped: .cursor/mcp.json · Global: ~/.cursor/mcp.json
{
"mcpServers": {
"jisr": {
"type": "stdio",
"command": "npx",
"args": ["-y", "jisr-mcp"],
"envFile": ".env"
}
}
}Cursor supports envFile for stdio servers, so credentials can stay in an untracked .env rather
than in the JSON. If you prefer inline, replace envFile with an env object.
Codex
Codex uses TOML, not JSON. User scope: ~/.codex/config.toml · Project scope:
.codex/config.toml (trusted projects only).
[mcp_servers.jisr]
command = "npx"
args = ["-y", "jisr-mcp"]
[mcp_servers.jisr.env]
JISR_BASE_URL = "https://apis.jisr.net/api"
JISR_SLUG = "your-organization-slug"
JISR_API_KEY = "..."
JISR_API_SECRET = "..."
JISR_ROLE_PROFILE = "hr_operations"Or via the CLI: codex mcp add jisr --env JISR_SLUG=... -- npx -y jisr-mcp.
Verify with codex mcp list.
Claude Desktop
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"jisr": {
"command": "npx",
"args": ["-y", "jisr-mcp"],
"env": {
"JISR_BASE_URL": "https://apis.jisr.net/api",
"JISR_SLUG": "your-organization-slug",
"JISR_API_KEY": "...",
"JISR_API_SECRET": "...",
"JISR_ROLE_PROFILE": "hr_operations"
}
}
}
}Restart Claude Desktop afterwards.
MCP Inspector
JISR_BASE_URL=... JISR_SLUG=... JISR_API_KEY=... JISR_API_SECRET=... \
JISR_ROLE_PROFILE=hr_operations \
npx @modelcontextprotocol/inspector npx -y jisr-mcpIf your tool list looks wrong
The tool list is filtered by your role profile and your key's permissions, so it legitimately differs between people. Some clients cache it and won't notice a configuration change — restart the client to refresh.
A missing tool is not a missing feature. Ask jisr_capabilities_get: it reports four independent
facts per operation — specification support, Jisr key permission, your role, operator configuration
— and names who can change whichever one declined.
Protocol versions
Ships two adapters over one core, so it works with clients on either protocol revision:
Adapter | Protocol | Default |
| 2026-07-28 | ✅ |
| 2025-11-25 | set |
Both present identical tools, inputs, outputs, error codes and annotations. The v1 adapter will be removed once the clients above have migrated.
Security
Financial and sensitive-identity tools are hidden unless the operator explicitly enables them, even when the Jisr key permits them.
Credentials never appear in a tool result, log, trace, or error.
Collections are scoped to the records your role can reach, before pagination — and no count discloses what lies outside it.
Audit records go to stderr as structured JSON. Nothing is written to disk.
See SECURITY.md and the governing principles in
.specify/memory/constitution.md.
Development
npm ci
npm run typecheck && npm run lint && npm test
npm run verify:coverage # implemented surface vs the approved Jisr spec snapshotSee CONTRIBUTING.md.
License and publisher
MIT — see LICENSE.
Published and maintained by Gamal Eldien as an independent, unofficial project. Not affiliated with, endorsed by, or supported by Jisr; built against Jisr's publicly documented Open API only.
Available Tools
11 toolsjisr_audit_events_listList audit eventsARead-onlyIdempotent
Lists Jisr audit events, filterable by module, event name, event type and date range. Filters are ordinary named inputs; the server encodes them into Jisr’s bracketed query syntax.
Inputs: cursor, toDate, fromDate, pageSize, +3 more.
jisr_business_units_listList business unitsARead-onlyIdempotent
Lists the organization's business units, each with its identifier and both English and Arabic names. Use these to resolve names to stable identifiers before filtering other tools.
Inputs: cursor, pageSize.
jisr_capabilities_getJisr capabilitiesARead-onlyIdempotent
Lists every documented Jisr operation and, for each, four independent facts: whether the specification supports it, whether the connected API key permits it, whether your role allows it, and whether the operator enabled it. Explains why anything unavailable is unavailable, and who can change that.
Inputs: no named parameters.
jisr_connection_status_getJisr connection statusARead-onlyIdempotent
Reports whether this server can reach Jisr, when it last authenticated, and the last authentication error if any. Returns no credentials or organization identifiers.
Inputs: no named parameters.
jisr_data_catalog_getJisr data catalogARead-onlyIdempotent
Describes the available Jisr domains: which tools serve them, what classified field groups each tool may return and why, how pagination works, and how fresh the data is. Returns no records.
Inputs: domain.
jisr_departments_listList departmentsARead-onlyIdempotent
Lists the organization's departments, each with its identifier and both English and Arabic names. Use these to resolve names to stable identifiers before filtering other tools.
Inputs: cursor, pageSize.
jisr_employment_types_listList employment typesARead-onlyIdempotent
Lists the organization's employment types, each with its identifier and both English and Arabic names. Use these to resolve names to stable identifiers before filtering other tools.
Inputs: cursor, pageSize.
jisr_locations_listList locationsARead-onlyIdempotent
Lists the organization's locations, each with its identifier and both English and Arabic names. Use these to resolve names to stable identifiers before filtering other tools.
Inputs: cursor, pageSize.
jisr_nationalities_listList nationalitiesARead-onlyIdempotent
Lists the organization's nationalities, each with its identifier and both English and Arabic names. Use these to resolve names to stable identifiers before filtering other tools.
Inputs: cursor, pageSize.
jisr_outsourcing_companies_listList outsourcing companiesARead-onlyIdempotent
Lists the organization's outsourcing companies, each with its identifier and both English and Arabic names. Use these to resolve names to stable identifiers before filtering other tools.
Inputs: cursor, pageSize.
jisr_webhooks_listList webhook subscriptionsARead-onlyIdempotent
Lists the organization’s webhook subscriptions: name, endpoint, HTTP method, status and subscribed events. Stored authentication material is never returned.
Inputs: cursor, pageSize.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool maps to a distinct resource: connection status, capabilities, seven reference-data lists, webhooks, audit events, and data catalog. The similar list tools are clearly separated by entity type, and the two metadata tools serve different purposes.
All tool names follow the same jisr_<resource>_<verb> pattern, using consistent snake_case and terminal _get or _list verbs. There is no mixing of conventions or vague generic verbs.
Eleven tools is well within the ideal range for a domain-specific MCP server. Each tool earns its place, covering reference data, metadata, and system visibility without unnecessary overlap.
The server thoroughly covers organizational reference data, capabilities, webhooks, and audit events, but it is almost entirely read/list-oriented. It lacks tools for core organizational entities beyond reference data, such as employees, and provides no create/update/delete operations, leaving notable gaps for broader Jisr workflows.
Maintenance
Related MCP Connectors
Read PaySpace employees, organization, payroll runs, payslips and leave records. Read-only.
Read-only, permission-scoped PIO team workflows for payments, payroll and employee onboarding.
Read-only access to InfluSense influencer discovery, ratings, watchlists, and reports via MCP.
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceProvides read-only access to TrustLayer's public API, enabling users to query and retrieve data about parties, documents, projects, and other TrustLayer entities through MCP-compatible tools.MIT
- AlicenseBqualityDmaintenanceEnables read-only access to FileMaker databases through the Data API, allowing users to retrieve records, analyze metadata, search across layouts, and infer relationships while maintaining data security.16MIT
- FlicenseNot gradedqualityCmaintenanceRead-only MCP server for Microsoft Entra ID (Azure AD) that enables querying user sign-in logs, group memberships, and assigned Microsoft 365 licenses via Microsoft Graph API. Provides security and audit visibility without any write operations.-
- FlicenseNot gradedqualityBmaintenanceProvides read-only access to Dooray collaboration services through REST, CalDAV, and LDAP, enabling queries for projects, tasks, calendar events, and directory information via 18 MCP tools.-