A production-grade Model Context Protocol server that connects Claude (or any MCP client) to SAP SuccessFactors via OData APIs. Query employee data, manage permissions, run compliance reports, and administer HR operations — all through natural language.
You: "Who on the Engineering team has a work anniversary this month?"
Claude: [calls get_anniversary_employees] Found 3 upcoming anniversaries...
- Jane Smith (5 years - milestone!) - March 12
- Bob Johnson (2 years) - March 18
- Alice Chen (10 years - milestone!) - March 25
Why SF-MCP?
Tools
62 tools organized across 16 categories:
Installation
Prerequisites
- Python 3.10+
- uv package manager
- SAP SuccessFactors account with API access
Setup
git clone https://github.com/aiadiguru2025/sf-mcp.git
cd sf-mcp
uv sync
Quick Start
Development mode (MCP Inspector):
uv run mcp dev main.py
Stdio mode (Claude Desktop):
uv run main.py
HTTP mode (Cloud Run / remote):
PORT=8080 uv run main.py
Claude Desktop Integration
Step 1 — Find the path to uv
# macOS / Linux
which uv
# Windows (PowerShell)
Get-Command uv | Select-Object -ExpandProperty Source
Step 2 — Edit your Claude Desktop config
Add the sf-mcp server:
{
"mcpServers": {
"sf-mcp": {
"command": "/path/to/uv",
"args": ["--directory", "/path/to/sf-mcp", "run", "main.py"]
}
}
}
Step 3 — Restart Claude Desktop
The MCP tools icon (hammer) will appear in the input area with all 62 tools available.
Note: Credentials (
auth_user_idandauth_password) are provided on each tool call — nothing is stored in the config.
Deployment
Google Cloud Run
# Build and deploy
export PROJECT_ID=your-gcp-project-id
gcloud builds submit --tag gcr.io/$PROJECT_ID/sf-mcp
gcloud run deploy sf-mcp \
--image gcr.io/$PROJECT_ID/sf-mcp \
--platform managed \
--region us-central1
Then point Claude Desktop to the remote URL:
{
"mcpServers": {
"sf-mcp": {
"url": "https://sf-mcp-xxxxx-uc.a.run.app/mcp"
}
}
}
Docker (local)
docker build -t sf-mcp .
docker run -p 8080:8080 sf-mcp
API Key Protection (optional)
Set MCP_API_KEY to require authentication on the HTTP endpoint:
MCP_API_KEY=your-secret-key PORT=8080 uv run main.py
Clients must then include X-API-Key: your-secret-key in requests.
Configuration
All tool parameters (data_center, environment, auth_user_id, auth_password) are provided per-request. Server-side environment variables are optional:
Rate Limiting
Response Caching
Endpoint Protection
Copy .env.example to .env to customize:
cp .env.example .env
Supported Data Centers
21 data centers across 6 continents with alias support:
Architecture
sf-mcp/
├── main.py # Entry point (stdio + HTTP modes)
├── sf_mcp/
│ ├── server.py # FastMCP instance
│ ├── config.py # DC mappings, constants, env vars
│ ├── auth.py # Credential resolution, API key middleware
│ ├── client.py # HTTP client (OData, metadata, service doc, pagination)
│ ├── cache.py # TTL-based response cache with deep-copy safety
│ ├── rate_limiter.py # Sliding-window rate limiter (per-instance)
│ ├── validation.py # 10 input validators with registry pattern
│ ├── decorators.py # sf_tool decorator (cross-cutting concerns)
│ ├── dependencies.py # FastMCP DI for schema exclusion
│ ├── logging_config.py # Cloud Logging JSON formatter, audit_log()
│ ├── xml_utils.py # Safe XML parsing (defusedxml), SAP date parsing
│ └── tools/ # 62 tools across 16 modules
│ ├── configuration.py # get_configuration, compare_configurations, list_entities
│ ├── permissions.py # 7 RBP security tools
│ ├── audit.py # Role history, role assignment history
│ ├── query.py # query_odata, get_picklist_values
│ ├── employee.py # Profile, search, history, team roster
│ ├── time_off.py # Balances, upcoming absences, requests
│ ├── recruiting.py # Requisitions, pipeline, new hires
│ ├── compliance.py # Terminations, missing data, anniversaries, reviews, comp
│ ├── position.py # Position details, vacancies, org chart
│ ├── workflow.py # Pending approvals, workflow history
│ ├── mdf.py # MDF object definitions, queries, foundation objects
│ ├── monitoring.py # Alerts, scheduled jobs, integration jobs
│ ├── admin.py # Rate limit quota, cache status, cache clear
│ └── utils.py # Shared utilities (display_name)
├── tests/ # 110 tests
├── Dockerfile # Cloud Run container
├── .env.example # Configuration template
└── pyproject.toml # Project metadata, dependencies, linter config
Design Principles
Zero boilerplate — The sf_tool decorator handles request ID generation, timing, audit logging, input validation, credential checking, error handling, and $top clamping. Tool functions contain only business logic.
Secure by default — 10 input validators (regex allowlists), OData injection prevention, XXE-safe XML parsing (defusedxml), timing-safe API key comparison (hmac.compare_digest), and automatic credential masking in logs.
Production-ready — Connection pooling (requests.Session), mutation-safe response caching (deep-copy on put/get), sliding-window rate limiting with automatic 429 retry, and Cloud Logging-compatible JSON audit trail.
Schema-clean — Internal parameters (request_id, start_time, api_host) are hidden from the MCP tool schema via FastMCP's Dependency injection, keeping tool interfaces clean for LLM consumers.
Security
Testing
# Run all 110 tests
uv run pytest tests/ -v
# Run with coverage
uv run pytest tests/ --cov=sf_mcp
# Lint
uv run ruff check .
# Type check
uv run mypy sf_mcp/
Test coverage includes:
- Config — DC mapping resolution, case insensitivity, aliases, error cases
- Validation — All 10 validators with valid/invalid inputs, injection prevention
- Client — Mocked HTTP responses (200, 401, 500, empty, connection error)
- Rate limiter — Limit enforcement, sliding window, per-instance isolation, thread safety
- Cache — Put/get, TTL expiry, category TTLs, invalidation, eviction, deep-copy safety
- Pagination — Single/multi page, max_pages limit, error handling, $skip increments
- Decorators — Value injection, validation errors, max_top clamping, exception handling
API Reference
Every tool accepts these common parameters:
get_configuration
Retrieve OData metadata for a SuccessFactors entity.
list_entities
Discover all available OData entities in an instance.
compare_configurations
Compare entity config between two instances (e.g., dev vs prod).
get_rbp_roles
get_role_permissions
get_user_permissions
get_user_roles
get_permission_metadata
check_user_permission
get_dynamic_groups
get_role_history
get_role_assignment_history
At least one of
role_idoruser_idis required.
get_login_audit_log
Requires the instance's Audit Trail / Login Tracking feature to be provisioned.
get_admin_audit_log
Requires the instance's Audit Trail feature to be provisioned.
get_sod_violations
get_dormant_users
query_odata
get_picklist_values
get_employee_profile
search_employees
get_employee_history
get_team_roster
get_time_off_balances
get_upcoming_time_off
get_time_off_requests
get_open_requisitions
get_candidate_pipeline
get_new_hires
get_terminations
get_employees_missing_data
get_anniversary_employees
get_performance_review_status
get_compensation_details
get_compensation_history
get_compensation_review_status
get_salary_range_analysis
Returns compa-ratio (current salary ÷ grade midpoint × 100) per employee.
get_goal_summary
get_development_plans
get_talent_flags
Field availability depends on the instance's Succession Data Model configuration.
get_succession_nominees
get_position_details
get_vacant_positions
get_org_chart
get_mdf_object_definitions
query_mdf_object
get_foundation_objects
get_pending_approvals
get_workflow_history
get_alert_notifications
get_scheduled_job_status
get_integration_center_jobs
get_api_quota_status
Returns current rate limit usage for the specified instance.
get_cache_status
Returns cache hit rates, entry counts by category, and memory usage.
clear_cache
get_global_assignments
get_employee_documents
get_pay_component_groups
get_work_permit_expiry
get_probation_end_dates
bulk_export_employees
get_picklist_usage
get_country_specific_fields
Example Queries
Ask Claude in natural language:
Common SuccessFactors Entities
Use list_entities to discover all available entities in your instance.
Troubleshooting
- Verify credential format: user ID without
@instance - Confirm the password is correct
- Ensure the API user has proper permissions in SuccessFactors Admin Center
All inputs are validated to prevent injection attacks:
- Verify
uvpath in config is correct:which uv - Check logs:
tail -f ~/Library/Logs/Claude/mcp*.log - Test manually:
uv run mcp dev main.py - Ensure Python 3.10+ is installed:
python3 --version
- The server auto-retries HTTP 429 responses (up to 3 times)
- Use
get_api_quota_statusto check current usage - Increase limits via
SF_RATE_LIMITenvironment variable - Cache responses with
SF_CACHE_TTL_DEFAULTto reduce API calls
Dependencies
Dev dependencies: pytest, ruff, mypy
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Run tests:
uv run pytest tests/ -v - Run linting:
uv run ruff check . - Commit your changes
- Open a Pull Request
Changelog
See CHANGELOG.md for release history.
License
This project is licensed under the MIT License — see the LICENSE file for details.