The Problem

Most HR platforms force a trade-off: SaaS products take your data and limit customization, while open-source options lack native AI integration. MintHCM targets organizations that want both full data ownership and AI-agent-driven HR processes without vendor lock-in.

What This Does

MintHCM is an open-source HCM platform built around AI agent integration. The api/ directory (4,134 files) contains the PHP backend handling auth, modules, and OAuth2. The mcp/ directory (927 files) implements the Model Context Protocol layer for AI agent connectivity, and vue/ (724 files) holds the frontend. A legacy/ directory (34,590 files) carries the original PHP codebase, so this is a mature project with substantial history.

Core HR functions—recruitment, onboarding, leave management, performance tracking—are implemented as modules under api/app/Controllers/, including RecruitmentController, LeaveController, and PerformanceController.

How It Is Wired

Execution starts at docker/docker-compose.yml, which orchestrates the stack. The API entry point is api/app/ApiManager.php, routing requests through api/app/Controllers/. The AuthController and OAuth2/ directory handle authentication, with FrontendGrant.php and MobileGrant.php managing token issuance.

The McpController.php is the critical hub—it exposes HR data and processes to external AI agents via MCP. This is where the "AI-native" claim materializes: agents authenticate, query employee data, and trigger workflows through this single controller. Everything routes through ApiManager.php first, so that file carries the widest blast radius—any change there affects all 4,000+ API files.

The dependency graph shows a cycle between api/app/Controllers/ and api/app/Entities/—entities are referenced by controllers and vice versa. Changing entity structures will ripple through controllers, requiring coordinated updates.

How To Use It

Setup: The docker/ directory provides the fastest path:

git clone https://github.com/moses-y/minthcm
cd minthcm
docker compose -f docker/docker-compose.yml up -d

Configuration: Environment variables live in docker/.env (flagged as containing secret-shaped paths—verify before production). Database credentials and OAuth keys go there.

Running it: The Docker compose file handles everything. For development, kanban/package.json implies npm scripts for the frontend, and api/composer.json handles PHP dependencies.

Real-World Use

A recruitment team deploys MintHCM on-premises. An AI agent connects via MCP to McpController.php, queries open positions, screens candidates from the Candidate entity, and updates application statuses—all without exposing the underlying database. The agent orchestrates interview scheduling and sends offers through the same API layer, and HR retains full control over data and infrastructure.

Code Health & Issues

Static analysis found one issue:

  • Low/Security - Secret-shaped paths present in docker/.env—verify whether actual credentials are committed or just placeholders.

Other observations from structure:

  • Med - 26,677 PHP files in legacy/ suggest significant technical debt; migrating to the newer api/ structure will be substantial.
  • Low - 934 test files exist, but no CI workflow beyond .github/workflows/main.yml—test coverage for the MCP layer is unclear.
  • Low - No license file detected at root, despite README claiming AGPL v3—confirm before production use.

The Bottom Line

MintHCM offers genuine AI-agent integration with real deployment flexibility, and the MCP architecture is a legitimate differentiator. The codebase is large and carries legacy weight, so plan for migration effort. It suits organizations that need AI-driven HR with full data control and have engineering resources to manage the complexity.