Skip to main content
Glama
successfactors-mcp

successfactors-mcp

by wudaoyou

SuccessFactors Toolkit

CI License Python

A self-hosted toolkit for SAP SuccessFactors API troubleshooting, payload extraction, and integration development, exposed as a REST API and as an MCP (Model Context Protocol) server.

API

Protocol

Endpoint prefix

EC SFAPI — Compound Employee

SOAP 1.1

/api/sfapi/ce/

OData

REST (v2, v4)

/api/odata/

OData v4 covers the SuccessFactors APIs published as v4 services (for example Calibration and Continuous Feedback); Employee Central and Onboarding data stay on v2. See OData API.

This is an independent project, not affiliated with or endorsed by SAP SE. SAP and SuccessFactors are trademarks of SAP SE.

Start here: Docker MCP → credentials → ask → export

Data security: prefer local deployment. For sensitive SuccessFactors employee data and credentials, we recommend running the MCP server in local Docker and using a local AI agent, rather than an online AI platform or a third-party hosted MCP service. Keep credentials and exports on your machine; do not upload private keys or employee payloads to online platforms.

A local AI agent is not necessarily a local model. If it calls a cloud model, prompts, tool responses, previews, and file contents supplied to that model may leave your machine. If HR data must stay within your controlled environment, use a locally hosted model and local file-processing tools, and check the agent's outbound data handling. Local Docker alone does not guarantee this. The toolkit still connects to your configured SuccessFactors tenant to query data.

For functional consultants and business key users, start with the business user guide or its English/Chinese HTML edition. Ask IT to complete the one-time Docker Compose setup and provide approved connection files. Then:

  1. Check Docker Desktop or your IT-managed Docker service is running, then open your local AI application.

  2. Confirm with IT that the connection files are in sf-toolkit/credentials/systems, one folder per SuccessFactors system.

  3. Confirm which SuccessFactors system to use and ask for the employee, date, and information you need.

  4. Find results under sf-toolkit/data/mcp. Ask a file-capable AI application for CSV or another supported format, or a copy in an authorized folder.

The guide includes example business questions, completion checks, troubleshooting, and expandable one-time settings for your administrator. Original OData results are JSON; Compound Employee results are XML. CSV conversion requires local file tools in the AI application.

Related MCP server: Archive MCP Server

Documentation

Page

Covers

REST API

Fail-closed setup, install and run, cheat sheet, response format

Connect to SuccessFactors

Key pair generation, system files (SYSTEMS_DIR/<name>/<name>.json), environment variables, system management

EC SFAPI (SOAP)

Compound Employee single lookup, structured filter query, pagination, known footguns

OData API

execute / extract / extract-by-filter-in, OData v4 services, per-request connection override, known API footguns

MCP server

Tools for AI agents, payload handling, export formats, PII tokenization, plugins

Development

Local dev setup, linting, tests, release process

Data handling

Use synthetic examples and test fixtures. Credentials, certificates, tenant exports, employee payloads, and generated results do not belong in Git — .gitignore and scripts/check_repository.py are a basic guardrail, not a complete secret or personal-data scanner. See SECURITY.md for deployment guidance and how to report a vulnerability.

License

Apache License 2.0. Copyright 2026 Justin Gong. See NOTICE for third-party and migrated-code attribution.

Available Tools

5 tools
ce_queryA

Query the EC Compound Employee (SOAP) API and save the payload to disk.

person_id_external / user_id are comma-separated and take precedence over every other filter when set. last_modified_on is an ISO datetime for a delta pull (SAP allows at most 3 months of look-back). With no filter at all this is a full extract, capped by max_pages.

CompoundEmployee SFQL allows only ONE condition on last_modified_on in the WHERE clause — a query with both a lower and an upper bound (last_modified_on>X and last_modified_on<=Y) fails with INVALID_SFQL: Only one condition is allowed. This tool only ever emits the lower bound; apply any upper bound to the returned rows client-side, not by adding a second last_modified_on condition.

last_modified_on's filtering also depends on an SFQL parameter, isNotFirstQuery, that this tool does not currently set: per tenant testing, a query without isNotFirstQuery ignores last_modified_on entirely and returns a full snapshot of the matching window, while isNotFirstQuery=true makes last_modified_on act as a real delta filter. Until this tool exposes that parameter, treat last_modified_on here as a full-window snapshot, not a guaranteed delta — don't rely on it alone to mean "only changed rows".

select_segments defaults to the widely supported COMMON_SEGMENTS. If SF answers INVALID_SFQL naming a segment, that module is not enabled on the tenant — pass a narrower list. Only documented segment names are accepted, and person_id_external / user_id values may contain only letters, digits, space and _ . @ : / + -.

Each queryMore page is written as its own XML file. The tool returns counts and paths only: one employee's payload is ~80 KB of HR data.

Inputs: user_id, max_rows, max_pages, company_id, +4 more. Returns: object

compare_metadataA

Compare the OData configuration of two instances and return the drift.

entity="EmpJob" compares one entity set; entity="" compares the whole service (v4: a service path, as in odata_metadata). The comparison runs here, not in the conversation: one instance's EmpJob metadata alone is ~40 KB, so diffing two of them in context is both expensive and easy to get wrong.

Returns in_sync plus, per entity, the fields missing on either side and the fields whose attributes differ, each as [value_in_a, value_in_b]. The sap: attributes are the configuration itself — required, visible, upsertable, picklist, MaxLength — so a changed picklist or a field that never left the dev instance shows up here.

Inputs: company_a (required), company_b (required), entity. Returns: object

list_tenantsA

List the SuccessFactors instances this server can reach.

Call this first: the company_id values it returns are what the other tools take as their company_id argument. An empty company_id always means the instance configured in the server's own .env, reported here as "default". "plugins" reports each installed plugin and whether it loaded. "production" is the tenant's declared environment; odata_query and ce_query refuse a tenant where it is null or "config_error" is set.

Inputs: no named parameters. Returns: object

odata_metadataA

Fetch OData $metadata (EDMX) and reduce it to a compact field map.

entity="" pulls the whole service metadata (large — hundreds of entity types); entity="EmpJob" pulls just that entity set. The full {entity: {field: attributes}} map is written to a JSON file, and a small map is returned inline as well, so two instances can be compared without ever loading raw EDMX into the conversation. When entity is given, its navigation properties (name, target entity type, filterable) are listed too — entity-scoped $metadata doesn't carry them, so this resolves them from the full service $metadata instead (fetched once per company_id per process, then cached); a lookup failure is reported as a warning and never blocks the field output above. Use the navigation names to scope filters into other entities via $filter (see the server's "Scope with EmpJob first" guidance and odata_query's docstring) instead of pulling whole entity sets and joining locally.

On a v4 tenant, entity is a service path: its root for the whole service ("talent/cdp/Learning.svc/v1"), or root plus entity set for one (".../Learning.svc/v1/Items"); both read that service's $metadata.

Inputs: entity, company_id. Returns: object

odata_queryA

Run an OData query, following next links until exhausted or max_pages.

path is the entity set and may carry query options, e.g. "FOCompany" or "EmpJob?$select=userId,jobCode" (v4 tenant: service root first, "talent/cdp/Learning.svc/v1/Items") — those are parsed out of path and merged into the request; pass options either way, but prefer params (params win on conflicts). Always $select only the fields you need. Effective-dated entities (EmpJob, Position, FO*, MDF) return ONLY today's time slice unless you pass fromDate=1900-01-01 and toDate=9999-12-31 (or asOfDate) in params. Scope with a population filter pushed through navigation in $filter (e.g. personNav/employmentNav/jobInfoNav/company in (...)) rather than pulling whole entity sets — see the server instructions.

When max_pages > 1 and no $orderby is given, one is added from the entity's key properties (reported as orderby_added) so $skip paging can't duplicate or skip rows; if keys are unknown or unsortable, or SF rejects it, the query runs without and a warning says so — then pass $orderby yourself. Same condition, without $top/$skip, also adds paging=snapshot on v2 (reported as paging_added); if SF rejects it for that entity, the retry drops it and warns. Rows are checked for duplicate keys when every key field is in the records (duplicate_records

  • warning if found). A final page exactly $top-sized with no next link gets a truncation warning (some MDF entities stop early); resume with $skip and an explicit $orderby.

Records are written to a JSON file; the tool returns counts, the field names of the first record, and the path. preview accepts 0-20; values above zero return that many records inline only when their serialized UTF-8 size is at most 16 KiB. Otherwise, inspect the saved file locally.

Inputs: path (required), params, preview, max_pages, +1 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool targets a distinct stage: tenant discovery (list_tenants), schema inspection (odata_metadata), drift comparison (compare_metadata), and two query surfaces split by protocol (odata_query for OData, ce_query for SOAP Compound Employee). The two query tools could momentarily be confused as 'the query tool,' but descriptions make the API split explicit. Boundaries are otherwise clear.

    Naming Consistency4/5

    All names are snake_case and group sensibly by API prefix (odata_*, ce_*), with metadata-related tools sharing the _metadata suffix. However, verb-based names (list_tenants, compare_metadata) mix with noun-based names (odata_query, ce_query, odata_metadata), so the pattern is readable but not a single uniform convention.

    Tool Count5/5

    Five tools is well-scoped for a read-only SuccessFactors integration server: one for discovery, two for metadata handling, and two for the distinct query protocols. Every tool earns its place and none feels redundant or trivial.

    Completeness4/5

    The surface covers the full read-only workflow: find tenants, inspect metadata, diff metadata across tenants, and query both OData and Compound Employee APIs. Gaps are minor (no direct entity-set listing shortcut or write operations), but since the server appears intentionally read-only, no critical agent dead-end exists.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables querying SAP SuccessFactors OData API metadata and managing Role-Based Permission (RBP) configurations. It provides tools for retrieving entity metadata, listing permission roles, and inspecting user-specific access rights through MCP-compatible clients.
      29
      15
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables querying enterprise records and retention policies from any MCP client over stdio, with read-only tools for searching records, fetching retention verdicts, identifying archival candidates, summarizing departments, forecasting retentions, and viewing audit history.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to query projects, fetch findings, trigger analysis, upload CycloneDX BOMs, and check async token status against an OWASP Dependency-Track instance via stdio.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to interact with the Crewmeister API over local stdio, covering operations for members, teams, time tracking, salary exports, and related platform resources.
      Apache 2.0