aiadiguru2025/sf-mcp

SuccessFactors-MCP

SAP SuccessFactors Model Context Protocol Server


Installation ·
Quick Start ·
62 Tools ·
Deployment ·
API Reference

---

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_id and auth_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:

Example Queries

Ask Claude in natural language:

Common SuccessFactors Entities

Use list_entities to discover all available entities in your instance.

Troubleshooting

Dependencies

Dev dependencies: pytest, ruff, mypy

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Run tests: uv run pytest tests/ -v
4. Run linting: uv run ruff check .
5. Commit your changes
6. 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.

---

Built with FastMCP · Powered by Model Context Protocol