Frappe HRMS MCP Server

An MCP server that exposes a Frappe or Frappe HRMS instance as tools for AI agents. It uses Frappe's standard REST API and whitelisted RPC methods; it does not install or modify a Frappe app and does not maintain a separate database.

Documentation

• Setup guide: Docker, Frappe credentials, MCP configuration, stdio setup, Streamable HTTP setup, smoke tests, and troubleshooting.

• Process walkthrough: how MCP, the Python server, FrappeClient, Frappe HRMS, and the database work together.

Related MCP server: Frappe Assistant Core

Capabilities

The server provides:

• HRMS DocType discovery and schema inspection

• Link-field option lookup

• Generic document list, get, create, and update operations

• Document submission, cancellation, and timeline lookup

• Employee search

• Leave balance lookup and leave application creation

• Attendance lookup and attendance creation

• Salary slip lookup

• HR dataset verification with leave, attendance, compensation, and potential LOP metrics

The server has two modes:

is intended for controlled setup or migration work. Neither mode bypasses Frappe permissions.

Quick Start

Install dependencies:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Then follow the setup guide for the complete Docker and MCP configuration steps.

Request Flow

flowchart LR
    A[AI agent] --> B[MCP client]
    B --> C[Frappe HR MCP server]
    C --> D[FrappeClient]
    D --> E[Frappe HRMS API]
    E --> F[(Frappe database)]

The MCP server validates tool input with Pydantic, sends authenticated REST or RPC requests through FrappeClient, and returns JSON results or structured errors. Frappe remains responsible for permissions, field validation, workflows, and persistence.

Important Behavior

• hrms_apply_leave creates a Leave Application; submission is a separate frappe_submit_document operation.

• Admin bulk creation sends one request per document and is not transactional.

• API credentials belong on the MCP server and should be supplied through environment variables or a protected .env file.

• Streamable HTTP should be protected by TLS, authentication, and network restrictions before being exposed outside a trusted local environment.

Project Layout

Frappe HRMS Model Context Protocol (MCP) Server

MCP server exposing any Frappe / Frappe HRMS instance as tools for LLM agents. Operates over Frappe's standard REST API and whitelisted RPC methods — no app modifications required.

Frappe HRMS MCP Server

An MCP server that exposes a Frappe or Frappe HRMS site to an MCP-compatible client. It provides schema discovery, generic document operations, workflow actions, and focused HR helpers. The server does not modify the Frappe site or install a Frappe app; it calls Frappe's REST resources and whitelisted RPC methods using an API key and secret.

What This Server Does

The Python process registers MCP tools with the selected transport. Each tool validates its input with Pydantic, calls the Frappe API through the shared FrappeClient, and returns JSON text to the MCP client. Frappe remains the source of truth for permissions, validation, workflows, and stored data.

flowchart LR
    A[MCP client or agent] -->|tool call| B[MCP server]
    B --> C[Pydantic input validation]
    C --> D[Domain or generic tool]
    D --> E[FrappeClient]
    E -->|Authorization: token key:secret| F[Frappe REST API]
    E -->|GET or POST /api/method| G[Frappe whitelisted RPC]
    F --> H[Frappe permissions and business rules]
    G --> H
    H --> E
    E --> D
    D --> B
    B -->|JSON result or structured error| A

Request paths

• Generic documents use /api/resource/<DocType> for list, get, create, update, and admin-only delete operations.

• Schema discovery uses the whitelisted frappe.desk.form.load.getdoctype method, with a DocType resource fallback.

• Leave-balance lookup calls the HRMS method hrms.hr.doctype.leave_application.leave_application.get_leave_balance_on.

• All requests use the configured timeout and the Frappe token header.

Operating Modes

The server has two modes. Mode controls which MCP tools are registered; it does not bypass Frappe permissions.

Production is the default and is the recommended mode for routine agents. Admin mode is intended for controlled setup or migration work. Bulk creation is implemented as a sequence of individual create requests; it is not a single transaction and may return both successes and errors.

Tool Reference

Discovery

The registry contains 54 curated HRMS DocTypes across Core HR, Attendance & Shifts, Leave Management, Payroll, Expenses & Travel, Recruitment, and Lifecycle. Schema lookup can also inspect a DocType outside that registry.

Generic documents and workflows

HR helpers

Prerequisites

• Python 3.10 or newer is recommended.

• A reachable Frappe or Frappe HRMS site.

• An API user with only the DocType and action permissions required by the tools you intend to expose.

• Dependencies installed from requirements.txt.

Install into a virtual environment:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Configuration

Set these environment variables or put them in a .env file in the project root (the current working directory is checked first):

FRAPPE_BASE_URL=https://erp.example.com
FRAPPE_API_KEY=your_api_key
FRAPPE_API_SECRET=your_api_secret
FRAPPE_MCP_MODE=production
FRAPPE_REQUEST_TIMEOUT=30

The CLI --mode argument overrides FRAPPE_MCP_MODE. The CLI --http and --port options select Streamable HTTP and its listening port; the default port is 8800.

Run It

Local stdio transport

.venv/bin/python run.py
.venv/bin/python run.py --mode admin

Stdio is the default and is suitable for desktop clients that launch the server process. The process reads MCP messages from stdin and writes protocol output to stdout.

Streamable HTTP transport

.venv/bin/python run.py --http --port 8800
.venv/bin/python run.py --http --mode admin --port 8801

Place HTTP behind TLS and an authenticated, access-controlled reverse proxy when it is reachable outside a trusted local network. The application itself uses the configured Frappe API credentials for upstream calls; do not treat the HTTP listener as an authentication boundary unless your deployment adds one.

MCP Client Configuration

Example stdio configuration for clients that support an mcpServers map:

{
  "mcpServers": {
    "frappe-hr-production": {
      "command": "/absolute/path/to/mcp/.venv/bin/python",
      "args": ["/absolute/path/to/mcp/run.py", "--mode", "production"]
    },
    "frappe-hr-admin": {
      "command": "/absolute/path/to/mcp/.venv/bin/python",
      "args": ["/absolute/path/to/mcp/run.py", "--mode", "admin"]
    }
  }
}

Keep production and admin configurations separate. Do not place API secrets in the client configuration; provide them through the process environment or a protected .env file.

Recommended Agent Sequence

For a write operation, an agent should:

1. Call hrms_list_doctypes when the exact DocType is uncertain.

2. Call frappe_get_doctype_schema to inspect required fields and field types.

3. Call frappe_get_link_options for referenced records such as Department or Leave Type.

4. Create or update the document.

5. Call frappe_submit_document separately when the business operation requires submission.

6. Read the resulting document or history when confirmation is needed.

The server does not infer business approvals or silently retry writes.

Errors and Limitations

Errors are returned as JSON text. Upstream Frappe errors preserve the HTTP status code and a safe message. Common cases include missing credentials (401), permission failures (403), missing records (404), conflicts (409), validation failures (417), connection failures (502), and timeouts (504).

This project does not provide a local database, queue, transaction boundary, audit store, rate limiter, or retry policy. Frappe's permissions and audit behavior apply, but deployment owners should provide network controls, credential rotation, monitoring, and backups appropriate to their environment.

Production Checklist

• Use HTTPS for FRAPPE_BASE_URL and protect API credentials as secrets.

• Create a dedicated Frappe API user with least-privilege roles.

• Run production mode for routine agents; expose admin mode only for a short, controlled setup window.

• Put Streamable HTTP behind TLS, authentication, and network restrictions.

• Set an explicit FRAPPE_REQUEST_TIMEOUT for the deployment.

• Monitor the MCP process and the Frappe site for failed requests and permission errors.

• Test the exact DocTypes and HRMS version used by your site before enabling write tools in production.