SF-MCP: SAP SuccessFactors MCP Server

A Model Context Protocol (MCP) server that provides tools for retrieving configuration metadata from SAP SuccessFactors OData APIs.

Overview

This MCP server enables Claude Desktop (or any MCP-compatible client) to query SAP SuccessFactors entity metadata. It fetches OData $metadata endpoints and returns the configuration as structured JSON.

Features

• get_configuration: Retrieve metadata for any SuccessFactors OData entity

• get_rbp_roles: List all Role-Based Permission roles

• get_role_permissions: Get permissions assigned to a specific role

• get_dynamic_groups: List permission groups (dynamic groups)

• get_user_permissions: Get all permissions for a specific user

• Automatic XML/JSON conversion

• Error handling with detailed error messages

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 are configured via environment variables (never hardcode them):

   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)

   For local development, copy .env.example to .env and fill in your values:

   cp .env.example .env

Usage

Running with MCP Dev Server

For development and testing:

Running Standalone

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Note: Use the full path to uv (find it with which uv on macOS/Linux or where uv on Windows).

Security: The env block in Claude Desktop config is stored locally and not synced. Replace placeholder values with your actual credentials.

After updating the config, restart Claude Desktop completely (Cmd+Q on macOS).

Available Tools

get_configuration

Retrieves OData metadata for a specified SuccessFactors entity.

Parameters:

Example Usage in Claude:

Response:

Returns a JSON object containing the parsed XML metadata, including:

• Entity type definitions

• Property definitions with types and constraints

• Navigation properties

• Associations and entity sets

Error Responses:

get_rbp_roles

Lists all RBP (Role-Based Permission) roles in the SuccessFactors instance.

Parameters:

Example Usage in Claude:

Response:

Returns a JSON object with:

• roles: Array of role objects (roleId, roleName, userType, lastModifiedDate)

• count: Number of roles returned

get_role_permissions

Gets all permissions assigned to a specific RBP role.

Parameters:

Example Usage in Claude:

Response:

Returns a JSON object with:

• role_id: The requested role ID

• permissions: Permission data with human-readable labels

get_dynamic_groups

Lists dynamic groups (permission groups) used in RBP rules for defining access and target populations.

Parameters:

Example Usage in Claude:

Response:

Returns a JSON object with:

• groups: Array of dynamic group objects

• count: Number of groups returned

get_user_permissions

Gets all permissions for a specific user based on their assigned roles.

Parameters:

Example Usage in Claude:

Response:

Returns a JSON object with:

• user_id: The requested user ID

• permissions: User's effective permissions from all assigned roles

Common SuccessFactors Entities

Here are some commonly used OData entities you can query:

• User - Employee/user data

• EmpEmployment - Employment information

• EmpJob - Job information

• Position - Position management

• JobRequisition - Recruiting requisitions

• Candidate - Recruiting candidates

• PerPersonal - Personal information

• PerPhone - Phone numbers

• PerEmail - Email addresses

• FOCompany - Company foundation object

• FODepartment - Department foundation object

• FOJobCode - Job code foundation object

Cloud Deployment (Google Cloud Run)

Deploy this MCP server to Google Cloud Run for remote access.

Prerequisites

• Google Cloud account with billing enabled

• Google Cloud CLI installed

• Docker installed (for local testing)

Local Testing with Docker

Deploy to Cloud Run

Claude Desktop Config (Remote Server)

After deployment, update your Claude Desktop config to use the Cloud Run URL:

Replace sf-mcp-xxxxx-uc.a.run.app with your actual Cloud Run URL (shown after deployment).

Security for Production

For production deployments, use Cloud Run secrets instead of plain environment variables:

Project Structure

Dependencies

• mcp[cli]>=1.25.0 - Model Context Protocol SDK

• requests>=2.31.0 - HTTP client library

• xmltodict>=0.13.0 - XML to dictionary parser

• python-dotenv>=1.0.0 - Environment variable loader

• uvicorn>=0.30.0 - ASGI server for HTTP transport

Troubleshooting

Server Disconnected Error

If Claude Desktop shows "server disconnected":

1. Verify uv path in config is correct (use full path)

2. Check Claude logs: tail -f ~/Library/Logs/Claude/mcp*.log

3. Test the server manually: uv run mcp dev main.py

Authentication Errors (HTTP 401)

• Verify username format: <user_id>@<company_id>

• Check password is correct

• Ensure API user has proper permissions

XML Parse Errors

The API may return HTML error pages instead of XML. The error response will include a preview of what was returned to help diagnose the issue.

Empty Response

• Verify the entity name is correct

• Check the API URL host matches your datacenter

Security Considerations

• Environment variables: Credentials are stored in environment variables, never in code

• .env: The .env file is excluded from version control

• Claude Desktop config: Credentials in claude_desktop_config.json are stored locally only

• Minimal permissions: Use a dedicated API user with only the required permissions

License

MIT License