successfactors-mcp
# SuccessFactors Toolkit
[](https://github.com/wudaoyou/successfactors-toolkit/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
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](docs/ODATA.md#odata-v4).
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](docs/DOCKER_MCP_GUIDE.md) or its
[English/Chinese HTML edition](docs/DOCKER_MCP_GUIDE.html).
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.
## Documentation
| Page | Covers |
|---|---|
| [REST API](docs/REST_API.md) | Fail-closed setup, install and run, cheat sheet, response format |
| [Connect to SuccessFactors](docs/CONNECT.md) | Key pair generation, system files (`SYSTEMS_DIR/<name>/<name>.json`), environment variables, system management |
| [EC SFAPI (SOAP)](docs/SFAPI.md) | Compound Employee single lookup, structured filter query, pagination, known footguns |
| [OData API](docs/ODATA.md) | `execute` / `extract` / `extract-by-filter-in`, OData v4 services, per-request connection override, known API footguns |
| [MCP server](docs/MCP_SERVER.md) | Tools for AI agents, payload handling, export formats, PII tokenization, plugins |
| [Development](docs/DEVELOPMENT.md) | 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](SECURITY.md) for
deployment guidance and how to report a vulnerability.
## License
[Apache License 2.0](LICENSE). Copyright 2026 Justin Gong. See
[NOTICE](NOTICE) for third-party and migrated-code attribution.
TDQS
Scored across 5 tools
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.
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.
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.
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.