sap-mcp-config
The standard way to manage SAP credentials for MCP servers.
General
If you're building an MCP server that connects to SAP, use this package. It gives you validated, type-safe configuration in both Go and Python with a single shared config file. No more reinventing credential loading, no more inconsistent formats between projects.
Both mcp-server-abap (Go) and sapgui.mcp (Python) use this package.
The default config path (~/.config/sap-mcp/systems.json) follows the XDG Base Directory Specification.
Features
- One config file, two languages - Go and Python read the same config, guaranteed by shared test fixtures
- JSON and YAML - use whichever format you prefer (auto-detected by file extension)
- Validates eagerly - reports all errors at once so users fix everything in one pass
- Secrets can stay out of the file -
${env:VAR}placeholders pull values from the environment, sosystems.jsonholds structure only and becomes safe to commit and share - Passwords never leak in print/log output - masked in
str()/repr()/fmt.Println()/fmt.Sprintf("%+v")(Go:fmt.Formatter; Python:pydantic.SecretStr) - Immutable after loading - frozen Pydantic models in Python; in Go, use the returned structs as read-only
.envfile support -SAP_CONFIG_FILEcan be set in a.envfile- Easy to extend - subclass
SAPSystemin Python or embed the struct in Go to add project-specific fields
License
MIT
Users
This section covers everything you need to connect an MCP server to your SAP system. No programming knowledge required.
Configuration File
Create ~/.config/sap-mcp/systems.json (or systems.yaml - format is auto-detected by file extension):
JSON
{
"default_system": "dev",
"systems": {
"dev": {
"connection_name": "DEV - ERP Development",
"host": "https://your-sap-system:44300",
"client": "100",
"user": "YOUR_USER",
"password": "YOUR_PASSWORD",
"language": "DE"
},
"prod": {
"connection_name": "PROD - ERP Production",
"host": "https://prod-sap:44300",
"client": "200",
"user": "PROD_USER",
"password": "PROD_PASSWORD",
"language": "EN"
}
}
}
YAML
default_system: dev
systems:
dev:
connection_name: "DEV - ERP Development"
host: "https://your-sap-system:44300"
client: "100"
user: YOUR_USER
password: YOUR_PASSWORD
language: DE
prod:
connection_name: "PROD - ERP Production"
host: "https://prod-sap:44300"
client: "200"
user: PROD_USER
password: PROD_PASSWORD
language: EN
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
connection_name |
string | no | "" |
SAP Logon connection entry name - must match the bold description text shown in the SAP Logon pad, not the System ID (SID). Used by desktop backends (e.g. SAP GUI) to open the correct connection. (See Finding your connection_name below.) |
host |
string | yes | SAP system base URL (must start with http:// or https://) |
|
client |
string | no | "" |
SAP client/mandant, must be exactly 3 digits (e.g. "100") |
user |
string | conditional | "" |
SAP username (omit for OAuth2) |
password |
string | conditional | "" |
SAP password (omit for OAuth2) |
language |
string | no | "EN" |
Login language: "DE" or "EN" |
tls_skip_verify |
bool | no | false |
Skip TLS certificate verification |
oauth2_client_id |
string | no | "" |
OAuth2 client ID for token-based auth |
Validation rules:
- At least one system must be defined
default_systemmust reference an existing system keyhostis required and must start withhttp://orhttps://client, if set, must be exactly 3 digitslanguage, if set, must be"DE"or"EN"- Either both
userandpasswordmust be set, or neither (for OAuth2)
Keeping secrets out of the config file
The string fields of a system - connection_name, host, client, user, password, language and oauth2_client_id - plus the top-level default_system may contain an ${env:VAR} placeholder, which is replaced with that environment variable's value when the config is loaded. This lets you split the file into two parts: the structure - which systems exist, their hosts, clients and connection names - stays in systems.json, while the credentials come from your environment, CI secret store, or password manager.
The result is a systems.json you can commit to a repository and share with your team:
{
"default_system": "dev",
"systems": {
"dev": {
"connection_name": "DEV - ERP Development",
"host": "https://dev-sap.example.com:44300",
"client": "100",
"user": "${env:SAP_DEV_USER}",
"password": "${env:SAP_DEV_PASSWORD}"
},
"prod": {
"connection_name": "PROD - ERP Production",
"host": "https://prod-sap.example.com:44300",
"client": "200",
"user": "${env:SAP_PROD_USER}",
"password": "${env:SAP_PROD_PASSWORD}"
}
}
}
Each variable has a name and a value. The name must match the name in your ${env:...} placeholder, and the value is the content, for example your SAP username. How you set the variables depends on your operating system.
On Linux and macOS, set the variables in your shell:
export SAP_DEV_USER=YOUR_DEV_USER
export SAP_DEV_PASSWORD=...
In PowerShell, export does not exist. Instead, you can store the variables permanently for your user account, from any folder:
[Environment]::SetEnvironmentVariable("SAP_DEV_USER", 'YOUR_DEV_USER', "User")
[Environment]::SetEnvironmentVariable("SAP_DEV_PASSWORD", '...', "User")
The first argument is the variable name and the second argument is the value. Write the value in single quotes, so that characters such as $ in a password are kept as typed. The third argument, "User", is the scope of the variable (your Windows user account) - keep it exactly as written.
PowerShell saves the commands you type in its history. To keep your password out of it, use the graphical way instead:
- Press the Windows key and search for "Edit environment variables for your account".
- Under "User variables", click "New".
- Enter the variable name (for example
SAP_DEV_USER) and its value, then confirm with OK. Confirm with OK in the "Environment Variables" window as well, otherwise the variable is not saved.
A program that is already running does not see new variables. Close the terminal and quit the application that starts the MCP server completely, then start it again.
Rules:
- Only the exact form
${env:NAME}is a placeholder, whereNAMEis a plain identifier: letters, digits and underscores, not starting with a digit. Anything that does not match that form is left alone as literal text - see the table below. - A placeholder can be the whole value or embedded in a larger string, and a string may contain several:
"host": "https://${env:SAP_HOSTNAME}:${env:SAP_PORT}".
What counts as a placeholder:
| In your config | Result |
|---|---|
${env:SAP_DEV_PASSWORD} |
Replaced. If the variable is unset, loading fails with an error |
https://${env:HOST}:${env:PORT} |
Both replaced |
${env:not an identifier} |
Literal text - spaces are not allowed in a name |
${env:2FA_TOKEN} |
Literal text - a name cannot start with a digit |
${SAP_PASSWORD} |
Literal text - missing the env: prefix |
$env:SAP_PASSWORD |
Literal text - missing the braces |
The important half of this table is the bottom: text that looks like a placeholder but does not match the exact form is used verbatim, so a near-miss such as ${SAP_PASSWORD} becomes your literal password rather than an error. A genuine placeholder whose variable is unset always fails loudly, so the two cases can never be confused.
- An unset variable is an error, reported alongside every other validation problem. It never resolves to an empty string - so a forgotten
exportcannot silently turn a user/password system into an OAuth2 one. - A variable that is set but empty is also an error.
SAP_PASSWORD=is the shape an unpopulated CI secret takes, and accepting it would strip the credential just as silently. - Substitution runs once. A value pulled from the environment is not scanned again, so a secret that happens to contain
${env:...}is kept as literal text rather than triggering a further lookup - and it does not matter whether that inner name refers to a real variable. - Placeholders are resolved in the fields listed above, in JSON and YAML alike. They are not resolved in
tls_skip_verify(which is a boolean, not a string) nor in the system names themselves. ${env:VAR}is resolved in.env-provided variables too, when you load viaload_default()/LoadDefault().
A missing variable is reported like any other error:
invalid configuration:
- system "dev": password references ${env:SAP_DEV_PASSWORD}, which is not set in the environment
- system "prod": user references ${env:SAP_PROD_USER}, which is set but empty
Finding your connection_name in SAP Logon
Open the SAP Logon pad - your systems appear in a table. The connection_name is the text in the Description or Name column (the leftmost column with the bold/display name). It is not the short System ID (SID):
Description or Name - use this as connection_name |
System ID (SID) | Instance Number | Message Server |
|---|---|---|---|
| Production S/4HANA | PRD | 00 | prd-ms... |
| DEV - ERP Development | DEV | 00 | dev-ms... |
| QA System | QAS | 01 | qa-ms... |
Multiple entries for the same SAP system
The dictionary key (e.g. "dev", "prod") is only used to look up systems in the config. It has no connection to the SAP system itself. The connection_name field is what identifies the SAP Logon entry for desktop backends. This distinction allows you to configure multiple entries for the same SAP system with different clients or credentials:
{
"default_system": "dev-100",
"systems": {
"dev-100": {
"connection_name": "DEV - ERP Development",
"host": "https://dev-sap.example.com:44300",
"client": "100",
"user": "DEV_USER",
"password": "DEV_PASSWORD"
},
"dev-200": {
"connection_name": "DEV - ERP Development",
"host": "https://dev-sap.example.com:44300",
"client": "200",
"user": "QA_USER",
"password": "QA_PASSWORD"
}
}
}
Both entries share the same connection_name (same SAP Logon entry) but use different clients and credentials.
MCP JSON Configuration
Once your systems.json is ready, whoever configured the MCP server needs to point it at the credentials file via SAP_CONFIG_FILE. Both servers below read the same file - this is the key advantage over putting credentials in each server's env block separately:
{
"mcpServers": {
"sap-abap": {
"command": "mcp-server-abap",
"env": {
"SAP_CONFIG_FILE": "/home/user/.config/sap-mcp/systems.json"
}
},
"sap-webgui": {
"command": "run-sapgui-mcp-server",
"env": {
"SAP_CONFIG_FILE": "/home/user/.config/sap-mcp/systems.json"
}
}
}
}
Developers
This section is for developers building or extending MCP servers that use this package.
Python
Installation
pip install sap-mcp-config
Usage
import sys
from pydantic import ValidationError
from sap_mcp_config import load_default
try:
# Load from SAP_CONFIG_FILE env var or ~/.config/sap-mcp/systems.json
cfg = load_default()
except FileNotFoundError:
print("Config file not found. Create ~/.config/sap-mcp/systems.json")
sys.exit(1)
except ValidationError as e:
print(f"Configuration error:\n{e}")
sys.exit(1)
# Access the default system
dev = cfg.get_default()
print(dev.host, dev.client, dev.user)
# Access a specific system
prod = cfg.systems["prod"]
print(prod.host, prod.client, prod.user)
# Password is a SecretStr - it won't leak in print/logs
print(dev) # password=SecretStr('**********')
# Access the actual password value when needed
password = dev.password.get_secret_value()
Extending the Configuration
Subclass SAPSystem to add your own fields:
from pydantic import ConfigDict
from sap_mcp_config import SAPSystem
class MySAPSystem(SAPSystem):
model_config = ConfigDict() # unfreeze for subclass
custom_timeout: int = 30
Development
uv sync --group dev
uv run pytest unittests
Or run individual checks:
uv run --group tests pytest unittests # unit tests
uv run --group linting ruff check src/sap_mcp_config # ruff
uv run --group type_check mypy --strict src/sap_mcp_config # mypy --strict
uv run --group coverage coverage run -m pytest unittests # coverage
Go
Installation
go get github.com/Hochfrequenz/sap-mcp-config
Usage
package main
import (
"fmt"
"os"
sapmcpconfig "github.com/Hochfrequenz/sap-mcp-config"
)
func main() {
// Load from SAP_CONFIG_FILE env var or ~/.config/sap-mcp/systems.json
cfg, err := sapmcpconfig.LoadDefault()
if err != nil {
fmt.Fprintf(os.Stderr, "Configuration error:\n%s\n", err)
os.Exit(1)
}
// Access the default system
dev := cfg.GetDefault()
fmt.Println(dev.Host, dev.Client, dev.User)
// Access a specific system
prod := cfg.Systems["prod"]
fmt.Println(prod.Host, prod.Client, prod.User)
// Password is safe to print - it won't leak
fmt.Println(dev) // Output: SAPSystem{ConnectionName:DEV - ERP Development Host:https://... Client:100 User:DEV_USER Password:*** Language:DE}
}
Extending the Configuration
Embed SAPSystem in your own struct:
type MySAPSystem struct {
sapmcpconfig.SAPSystem
CustomTimeout int `json:"custom_timeout"`
}
Development
go test ./...
Error Messages (Python and Go)
Both implementations validate eagerly and return all errors at once. A misconfigured file like this:
{
"default_system": "missing",
"systems": {
"dev": { "host": "ftp://wrong", "client": "1", "user": "u" }
}
}
...will report all problems in a single error:
invalid configuration:
- default_system "missing" not found in systems
- system "dev": host must start with http:// or https://, got "ftp://wrong"
- system "dev": client must be a 3-digit string (e.g. "100"), got "1"
- system "dev": must have both user and password, or neither (for OAuth2)
Metadata
Release files for sap-mcp-config 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sap_mcp_config-1.1.1.tar.gz | 122.1 kB | With provenance | Details for sap_mcp_config-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sap_mcp_config-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for sap_mcp_config-1.1.1-py3-none-any.whl |
Total release size: 137.8 kB
Release files / sap_mcp_config-1.1.1.tar.gz
| Download URL | sap_mcp_config-1.1.1.tar.gz |
|---|---|
| Size | 122.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aba0ea68886f507dcf102d2eb6da2ea51dda89c21c780468fc5916d46c985c89
|
|
BLAKE2b-256 checksum How to use checksums |
ab3ed7b9f17c8feab601ef35a0a23cce14da28286d58a4b1175337004bbab7ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logRelease files / sap_mcp_config-1.1.1-py3-none-any.whl
| Download URL | sap_mcp_config-1.1.1-py3-none-any.whl |
|---|---|
| Size | 15.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f245e48eb759df02a3635a5d5d1331faa3ef53e441b8c1a6ec707eae59b2b655
|
|
BLAKE2b-256 checksum How to use checksums |
25438fefc008e304fdf4201db666e33fe899381686df2d32b6bcfd566b61b8d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logSecurity for sap-mcp-config 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sap_mcp_config-1.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.