SF-MCP: SAP SuccessFactors MCP Server

A secure Model Context Protocol (MCP) server providing 12 tools for querying and managing SAP SuccessFactors via OData APIs.

Overview

This MCP server enables Claude Desktop (or any MCP-compatible client) to interact with SAP SuccessFactors. It provides tools for configuration management, role-based permissions (RBP), data querying, and cross-instance comparison.

Features

Tools (12 total)

Security Features

• Input Validation: Regex-based validation prevents OData injection attacks
• XXE Protection: Uses defusedxml library for safe XML parsing
• Audit Logging: JSON-structured logs compatible with Cloud Logging
• Secret Manager: GCP Secret Manager integration for credential storage
• Credential Flexibility: Pass credentials per-request or use environment defaults

Prerequisites

• Python 3.10 or higher
• uv package manager
• SAP SuccessFactors account with API access

Installation

1. Clone or download this repository

2. Install dependencies

   cd sf-mcp
   uv sync
   

3. Configure credentials

   Credentials can be provided in three ways (in order of precedence):

   1. Per-request parameters: auth_user_id and auth_password on each tool call
   2. Environment variables: SF_USER_ID and SF_PASSWORD
   3. GCP Secret Manager: Secrets named sf-user-id and sf-password

   Variable	Required	Description
   SF_USER_ID	Yes*	Your SuccessFactors user ID (without @instance)
   SF_PASSWORD	Yes*	Your SuccessFactors password
   SF_API_HOST	No	API host (defaults to api55preview.sapsf.eu)

   *Required unless using per-request credentials or Secret Manager

Usage

Running with MCP Dev Server

For development and testing:

uv run mcp dev main.py

Running Standalone

uv run main.py

Claude Desktop Integration

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sf-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/sf-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "SF_USER_ID": "your_user_id",
        "SF_PASSWORD": "your_password"
      }
    }
  }
}

For Cloud Run deployment:

{
  "mcpServers": {
    "sf-mcp": {
      "url": "https://sf-mcp-xxxxx-uc.a.run.app/mcp"
    }
  }
}

Tool Reference

Configuration Tools

get_configuration

Retrieves OData metadata for a specified SuccessFactors entity.

Example:

Get the configuration metadata for the "User" entity in instance "mycompany"

list_entities

Discover all available OData entities in an instance.

Response:

{
  "entities": ["User", "Position", "EmpEmployment", ...],
  "count": 150,
  "total_available": 500,
  "by_category": {
    "foundation": 85,
    "employee": 120,
    "talent": 45,
    "platform": 30,
    "other": 220
  }
}

compare_configurations

Compare entity configuration between two instances (e.g., dev vs prod).

Response:

{
  "entity": "User",
  "comparison": {
    "fields_only_in_instance1": ["customField1"],
    "fields_only_in_instance2": ["customField2"],
    "fields_in_both": 45,
    "type_differences": [],
    "match_percentage": 95.5
  },
  "summary": {
    "is_identical": false,
    "differences_found": 2
  }
}

RBP Security Tools

get_rbp_roles

Lists all Role-Based Permission roles.

get_role_permissions

Gets permissions assigned to specific RBP roles. Supports multiple role IDs.

get_user_permissions

Gets all permissions for specific users based on their assigned roles.

get_user_roles

Gets all RBP roles assigned to a specific user.

Response:

{
  "user_id": "admin",
  "roles": [
    {"roleId": "10", "roleName": "Administrator", "roleDesc": "Full access"},
    {"roleId": "20", "roleName": "HR Manager", "roleDesc": "HR functions"}
  ],
  "role_count": 2
}

get_permission_metadata

Maps UI labels to permission types and values.

check_user_permission

Check if a user has a specific permission for a target user.

get_dynamic_groups

Lists dynamic groups (permission groups) used in RBP rules.

Data Query Tools

query_odata

Execute flexible OData queries against any SuccessFactors entity.

Examples:

# Get active users
entity="User", filter="status eq 'active'", select="userId,firstName,lastName"

# Get single user with expanded info
entity="User('admin')", expand="empInfo"

# Paginate through positions
entity="Position", top=100, skip=100

Response:

{
  "entity": "User",
  "results": [...],
  "count": 100,
  "next_skip": 200
}

Data Validation Tools

get_picklist_values

Get all values for a specific picklist (dropdown options).

Common Picklists:

• ecJobFunction - Job functions
• ecJobCode - Job codes
• ecPayGrade - Pay grades
• ecDepartment - Departments
• nationality - Countries/nationalities
• maritalStatus - Marital status options

Response:

{
  "picklist_id": "nationality",
  "locale": "en-US",
  "values": [
    {"id": "US", "externalCode": "US", "label": "United States", "status": "active"},
    {"id": "UK", "externalCode": "UK", "label": "United Kingdom", "status": "active"}
  ],
  "count": 195,
  "has_inactive": true
}

Common SuccessFactors Entities

Use list_entities to discover all available entities in your instance.

Cloud Deployment (Google Cloud Run)

Prerequisites

• Google Cloud account with billing enabled
• Google Cloud CLI installed

Deploy with Secret Manager (Recommended)

# Set project
export PROJECT_ID=your-gcp-project-id
gcloud config set project $PROJECT_ID

# Enable required APIs
gcloud services enable secretmanager.googleapis.com run.googleapis.com

# Create secrets
echo -n "your_user_id" | gcloud secrets create sf-user-id --data-file=-
echo -n "your_password" | gcloud secrets create sf-password --data-file=-

# Grant access to Cloud Run service account
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
gcloud secrets add-iam-policy-binding sf-user-id \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"
gcloud secrets add-iam-policy-binding sf-password \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# Build and deploy
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 \
  --set-env-vars "GCP_PROJECT_ID=$PROJECT_ID"

Local Testing with Docker

# Build the image
docker build -t sf-mcp .

# Run locally
docker run -p 8080:8080 \
  -e SF_USER_ID=your_user \
  -e SF_PASSWORD=your_pass \
  sf-mcp

# Test endpoint
curl http://localhost:8080/mcp

Project Structure

sf-mcp/
├── main.py              # MCP server with 12 tools
├── pyproject.toml       # Project dependencies
├── uv.lock              # Dependency lock file
├── Dockerfile           # Container image for Cloud Run
├── .env                 # Local credentials (gitignored)
├── .gitignore           # Git ignore rules
└── README.md            # This documentation

Dependencies

• fastmcp>=2.0.0 - Model Context Protocol SDK
• requests>=2.31.0 - HTTP client library
• defusedxml>=0.7.0 - Safe XML parsing (XXE protection)
• python-dotenv>=1.0.0 - Environment variable loader
• uvicorn>=0.30.0 - ASGI server for HTTP transport

Troubleshooting

Authentication Errors (HTTP 401)

• Verify credentials format: user ID without @instance
• Check password is correct
• Ensure API user has proper permissions in SuccessFactors

Validation Errors

The server validates all inputs to prevent injection attacks. If you see validation errors:

• instance: Must contain only alphanumeric, underscores, hyphens
• entity: Must be valid OData entity name
• filter: Cannot contain blocked keywords ($batch, $metadata, script tags)
• locale: Must be format like "en-US" or "de"

Server Disconnected

1. Verify uv path in config is correct
2. Check logs: tail -f ~/Library/Logs/Claude/mcp*.log
3. Test manually: uv run mcp dev main.py

Security Considerations

• Input Validation: All parameters validated with regex patterns
• XXE Protection: XML parsing uses defusedxml library
• Audit Logging: All tool invocations logged in JSON format
• Secret Manager: Production credentials stored in GCP Secret Manager
• No Hardcoded Secrets: Credentials from environment or parameters only
• Minimal Permissions: Use dedicated API user with required permissions only

License

MIT License