Skip to main content
Glama
HCM MCP Server for Oracle Fusion Cloud (unofficial)

HCM MCP Server for Oracle Fusion Cloud (unofficial)

HCM MCP Server for Oracle Fusion Cloud (unofficial)

Not affiliated with or endorsed by Oracle. Oracle and Fusion are trademarks of Oracle Corporation.

An MCP server that lets AI models interact with Oracle Fusion Cloud HCM across its entire REST surface — workers, org structures, compensation, absence, payroll, recruiting, talent, learning and more — without hand-coding a tool per endpoint.

Built to be packaged once and reused across many Fusion HCM customers, regardless of which modules they license, how their flexfields are configured, or which Oracle release they run.

Status: Feature-complete. All 16 tools implemented — discovery, generic read, 7 curated HR workflows, ATOM change feeds, and gated writes — with an inescapable client-layer PII-redaction + audit floor. Built on ADF REST behavior verified against a live Fusion pod (DESIGN.md §13). 60 unit tests; Docker image and stdio server boot verified. After installing, run the smoke checklist in docs/TEST_CASES.md against your pod (every pod's licensing, roles, and flexfields differ).


Why this exists

Oracle Fusion HCM exposes ~600 REST resources built on Oracle's uniform ADF REST framework. A naive MCP server would create one tool per resource and blow up the model's context window — and would advertise tools that don't exist for customers who haven't licensed the matching module.

This server takes the opposite approach: a small set of generic, schema-aware tools that introspect any resource at runtime via Oracle's /describe endpoint, plus a handful of curated workflow tools for the most common HR tasks. It discovers each customer's licensed footprint automatically and only exposes what actually works on their pod.

Related MCP server: OpenAPI MCP Server

Key design principles

  • Generic over hardcoded — 6 generic tools + ~15 curated workflows cover all ~600 resources. No per-resource code.

  • Self-documenting — the model reads live schemas via describe_resource; no bundled schema files to maintain.

  • Capability-aware — startup probing detects which Oracle modules are licensed/provisioned and lights up only those tool groups (no Recruiting license → no Recruiting tools).

  • Safe by default — read-only out of the box; writes are off by default, gated, dry-run-first, and audited. PII (national IDs, salary, DOB) is redacted unless explicitly enabled.

  • Distributable — one configurable artifact, deployed single-tenant per customer pod. No customer specifics in code.

Architecture at a glance

auth/     Basic + OAuth2/JWT (OCI IAM / IDCS)
core/     ADF REST client · resource catalog · /describe cache · q= filter builder
tools/    discovery · query · workflows · mutate · atom · bip
safety/   PII redaction · audit log · dry-run gates (writes off by default, schema-validated, fail closed)
config.py base URL · pinned REST version · scopes · feature & module flags

Tools (16)

Group

Tools

Diagnostics

server_info

Discovery

list_resources · describe_resource · get_capabilities

Read

query_resource · get_record

Workflows

find_worker · get_worker_profile · list_direct_reports · get_reporting_chain · lookup_org · get_current_compensation · list_absences

Change feeds

list_changes (ATOM — gated by features.atom_enabled)

Writes

mutate_record · run_action (gated by features.writes_enabled, dry-run default, schema-validated)

The generic query_resource / get_record / describe_resource work against any of the ~600 HCM resources; the workflows are curated shortcuts for common HR questions.

Roadmap

Phase

Deliverable

Status

1

Generic read core + auth + discovery + safety floor

✅ Built

2

Curated HR workflow tools

✅ Built

3

Gated writes + custom actions + audit

✅ Built

4

ATOM change feeds

✅ Built

5

BI Publisher / HCM Extracts reporting

◻ Future

Stack

Python · FastMCP · httpx · pydantic Packaged as a Docker/OCI image (primary) built from a hatchling wheel.

Getting started

Install from PyPI

pipx install fusion-hcm-mcp-server    # or: uvx fusion-hcm-mcp-server

pypi.org/project/fusion-hcm-mcp-server — published from this repo's CI via PyPI Trusted Publishing with attestations.

Want to use this from Claude Desktop? Follow the step-by-step guide: docs/INSTALL_CLAUDE_DESKTOP.md — covers both install modes (Python venv + OS credential store, or Docker), the Desktop config file, a test sequence, and the common traps.

Configure

cp config.example.toml config.toml   # then edit; supply secrets via HCM_* env vars

Required: server.base_url (or HCM_BASE_URL). Credentials should come from environment variables (HCM_USERNAME/HCM_PASSWORD, or HCM_CLIENT_ID/HCM_CLIENT_SECRET/HCM_TOKEN_URL), never the committed file. See config.example.toml.

Run with Docker (primary)

Prebuilt images are published to GitHub Container Registry on every release:

docker pull ghcr.io/mohantyajitesh/fusion-hcm-mcp-server:latest
docker run --rm -i \
  -e HCM_BASE_URL="https://your-pod.fa.ocs.oraclecloud.com" \
  -e HCM_USERNAME="INTEGRATION_USER" -e HCM_PASSWORD="..." \
  -v "$PWD/config.toml:/app/config.toml:ro" \
  ghcr.io/mohantyajitesh/fusion-hcm-mcp-server:latest

Or build from source: docker build -t fusion-hcm-mcp-server .

For hosted HTTP transport, set transport.type = "http" (or HCM_TRANSPORT=http) and publish -p 8000:8000.

Local development

Requires Python 3.11+.

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
fusion-hcm-mcp-server          # runs the MCP server over stdio

Documentation

  • docs/INSTALL_CLAUDE_DESKTOP.md — install & run with Claude Desktop (venv or Docker), verification sequence, troubleshooting traps.

  • docs/TEST_CASES.md — tool matrix, automated coverage, the live-pod checklist, production-readiness assessment.

  • DESIGN.md — full technical design: auth, the ADF REST client, exact tool signatures, the q= filter grammar, the safety model, ADF ground truth, and licensing/module alignment.

Status & contributions

This is an actively developing project — issues and PRs from people testing against their own pods are genuinely wanted. See CONTRIBUTING.md; for vulnerabilities, SECURITY.md. The design doc is the source of truth.

License

Apache-2.0. See also NOTICE.


Not affiliated with or endorsed by Oracle. Oracle and Fusion are trademarks of Oracle Corporation.

Available Tools

6 tools
describe_resourceA

Return a resource's live schema: attributes, child collections, actions.

Hits Oracle's /describe endpoint (cached). This is the authoritative source of field names to use in fields= and q= filters.

Inputs: resource (required). Returns: object

get_capabilitiesA

Report which HCM modules are live on this pod.

For each module: its mode (on/off/auto) and discovered status (enabled/disabled/provisioned/not_provisioned/no_access/unreachable). Modules set to auto are probed against the pod. Pass refresh=True to re-probe.

Inputs: refresh. Returns: object

get_recordA

Fetch a single record by its key, optionally expanding child collections.

key is the resource's primary key (e.g. PersonId for workers). Sensitive fields are redacted unless the deployment enables them.

Inputs: key (required), resource (required), expand, fields. Returns: object

list_resourcesA

Search the catalog of common Oracle Fusion HCM REST resources.

Works offline from a bundled seed list. Filter by search (matches name/title/description) and/or module (e.g. core_hr, compensation, absence, payroll, recruiting, talent, learning, benefits, time_labor). Use describe_resource to confirm a resource's live schema.

Inputs: limit, module, search. Returns: object

query_resourceA

Query any Oracle Fusion HCM resource (the generic read workhorse).

  • q: ADF filter, e.g. PersonNumber = 100010 or LastName LIKE 'Sm%'.

  • fields: restrict returned attributes (strongly recommended to keep responses small). Use describe_resource to find valid names.

  • expand: child collections to inline. Sensitive fields (national IDs, salary, DOB) are redacted unless the deployment enables them. Filters are validated against the schema first.

Inputs: resource (required), q, limit, expand, +4 more. Returns: object

server_infoA

Report non-sensitive server configuration and enabled module flags.

Safe to call without a live pod connection — useful for verifying a deployment's configuration before exercising the HCM API.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct responsibility: schema exploration (describe_resource), module status (get_capabilities), single record retrieval (get_record), resource catalog (list_resources), generic query (query_resource), and server configuration (server_info). No two tools overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case: describe_resource, get_capabilities, get_record, list_resources, query_resource, server_info. The pattern is uniform and predictable.

    Tool Count5/5

    With 6 tools, the set is concise yet covers the core needs for an HCM API exploration server: metadata discovery, querying, and configuration info. No tool is superfluous, and the count feels well-scoped for the domain.

    Completeness4/5

    The tool surface is complete for read and exploration tasks, providing schema discovery, resource catalog, and data retrieval. However, it lacks mutation operations (create/update/delete), which may be required for full HCM workflows, hence a minor gap.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A generic MCP server that dynamically converts OpenAPI-defined REST APIs into tools for LLMs like Claude. It supports multiple authentication methods and transport protocols, enabling seamless interaction with any OpenAPI-compliant API.
      18 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A generic MCP server that dynamically exposes any OpenAPI-documented REST API to LLMs by auto-discovering endpoints. It provides tools for exploring API capabilities and making authenticated requests directly through natural language interfaces.
      2
      11 npm
      MIT
    • A
      license
      B
      quality
      F
      maintenance
      A Model Context Protocol (MCP) server that enables AI assistants to query and understand PeopleSoft HCM databases. It provides semantic tools for HR, Payroll, Benefits, Performance, and PeopleTools metadata, allowing natural language questions to be answered with accurate SQL queries.
      43
      12
      MIT