# MintHCM

AGPL HR platform with time and attendance, leave and resource booking, shipping its own MCP server module with OAuth 2.1.

MintHCM is a SuiteCRM-derived human capital management system: recruitment, onboarding, employee records, competences, time and attendance, leave, resource and workplace booking, reporting, with iOS and Android apps. The repo carries an mcp/ module that serves an MCP endpoint at <site_url>/mcp behind OAuth 2.1 with PKCE, alongside a JSON:API-style REST API (Api/V8) that reads and writes any module. There is no shift rostering or payroll.

Alternative to: BambooHR, Personio

- Capabilities: adaptable, operable
- Vertical: scheduling-staffing
- Shape: business-app
- Form factor: web-app
- Execution model: hybrid
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/minthcm/minthcm (AGPL-3.0), 432 stars, last commit 2026-08-20
- Last activity: 2026-08-20
- Page: apps/minthcm--minthcm.html
- JSON: apps/minthcm--minthcm.json

## Use it when

- I need an HR system for a 50 to 500 person company that I host, with leave, attendance and room booking, and I want agents to work inside it
- I want to build HR copilots on my own employee data without sending it to a SaaS

## Gotchas

- AGPL-3.0 copyleft
- Heavy for an SMB: Apache with mod_rewrite and AllowOverride, PHP 8.2, MySQL or MariaDB, and Elasticsearch 7.10+ are required
- No shift rostering and no payroll; this is HR administration, not staffing
- Zero open GitHub issues on a 432-star repo: support runs through the minthcm.org forum and Discord, so issue history is not a signal here
- MCP discovery URLs depend on the root .htaccess generated by MintCLI; a hand installation must reproduce it

## Editions

- Free: Free, open source
  - source: https://github.com/minthcm/minthcm
  - container: https://github.com/minthcm/minthcm/tree/main/docker
- Implementation services: Free, closed source
  - hosted: https://minthcm.com/

## Adaptable: make it yours

Effort: config-only (6 things to edit)

Deploy with docker/docker-compose.yml and docker/.env or the MintCLI installer, which also writes the root .htaccess the MCP module needs. Runtime settings follow the SuiteCRM pattern under legacy/ (config and config_override files); modules, fields, workflows and the Vue UI are customizable in-app and at framework level. The MCP module in mcp/ has its own composer setup and a SKILL.md for clients. Model provider for the built-in agent is chosen per instance.

- Env vars: none
- Config files: docker/docker-compose.yml, docker/.env, docker/config, mcp/SKILL.md, legacy/config_override.php (SuiteCRM-derived; path not verified this run)
- Prompt files: mcp/SKILL.md
- Accounts you'll need: a model provider for the built-in agent (optional)

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://github.com/minthcm/minthcm/tree/main/mcp (published by the builder, local).

### Reach (partial coverage)

- Read and update employee records: reachable. Api/V8 JSON:API CRUD on any module (minthcm.org/support/how-to-use-mint-api); MCP module in repo
- Leave requests and balances: reachable. leave management module; module records are reachable through Api/V8
- Time and attendance entries: reachable. time and attendance module; Api/V8 module CRUD
- Book resources and workplaces: reachable. resources booking module; Api/V8 module CRUD
- Manage candidates and recruitment: reachable. recruitment module; Api/V8 module CRUD
- Run onboarding and offboarding processes: undetermined. modules exist; whether process steps are driven through API or only the UI is not documented
- Run reports: undetermined. reporting module; no API or MCP tool for report execution seen
- Look up how-to guidance from inside the agent: reachable. mcp/SKILL.md: browse_documentation and get_documentation_entry tools
- Shift scheduling and rostering: not reachable. not a module: minthcm.org lists time management, calendar and leave, no shift roster
- Payroll: not reachable. minthcm.org: payroll requires external integration

## Code stack

- Languages: PHP, TypeScript
- Frameworks: Vue, SuiteCRM, SugarCRM CE
- Package manager: composer
- Database: MySQL, MariaDB, Elasticsearch
- Hosting target: apache, docker, on-premise

## Model stack

- Providers: LLM-agnostic per README: OpenAI, Anthropic, Mistral, local Llama
- Models: none
- Keys you need (names only): none
- Prompts live in: mcp/SKILL.md
- Tools: browse_documentation, get_documentation_entry

## Skills

bundled: A single SKILL.md next to the bundled MCP server, teaching an agent to drive MintHCM through it.
- Paths: mcp/SKILL.md

## Evidence and confidence

- formFactor: README: Apache-served PHP application with a Vue front end and mobile apps (confidence 0.9)
- executionModel: README: built-in AI agent, LLM-agnostic; core HR modules are deterministic (confidence 0.6)
- operability: mcp/ directory in the Builder's repo with OAuth 2.1 README; Api/V8 REST documented on minthcm.org (confidence 0.85)
- effort: docker/ directory with docker-compose.yml, .env and config; MintCLI installer in repo (confidence 0.5)
- editions: README and minthcm.org: free, no license fees, self-hosted; paid implementation from minthcm.com (confidence 0.85)
- active: shortlist pushedAt 2026-08-20; minthcm.org reports 37,800+ downloads
- reach:  (confidence 0.6)

## Open questions

- Which MCP tools exist beyond the two documentation tools in mcp/SKILL.md? Read mcp/Capabilities
- Exact SuiteCRM-derived config file paths under legacy/ were not verified; confirm config_override.php before quoting it
- Builder describes the architecture as agent-native; recorded as official because the HR UI remains primary. Curator to decide
- Which env var names does docker/.env carry?

## Sources

- https://github.com/minthcm/minthcm (sourcing:scheduling-staffing:curated)
- https://minthcm.org/ (sourcing:scheduling-staffing:curated)
- https://minthcm.org/support/how-to-use-mint-api/ (analysis:scheduling-staffing)
- https://github.com/minthcm/minthcm/blob/main/mcp/README.md (analysis:scheduling-staffing)