sap-abap-mcp

A local Model Context Protocol server that lets Codex and Claude work with SAP ABAP through the official ABAP Development Tools (ADT) HTTP services.

It can inspect and edit ABAP source, run quality checks, manage transports, use abapGit and the RAP generator, inspect runtime data, compare systems, and perform repository refactorings without VS Code, SAP GUI, or an ABAP FS virtual workspace.

Release status

• Package: @coaspe/sap-abap-mcp
• Current release: 0.3.0
• Runtime: Node.js 20 or later
• Transport: local MCP over stdio
• Authentication: SAP Basic Auth
• Secret storage: macOS Keychain or Windows DPAPI
• SAP API client: abap-adt-api 8.4.1
• ABAP FS compatibility baseline: 2.6.5, commit 3041418d35558e043993a4d7f9fa6b727fcf9cf1

The automated suite validates the MCP contract, ADT argument ordering, safety policies, stale-preview protection, output bounds, and all 50 registered tools with an in-memory SAP implementation. Live SAP acceptance testing is still required because endpoint availability and authorization vary by SAP release and system configuration.

What it supports

The server preserves all 42 MCP tools exposed by ABAP FS 2.6.5 and adds eight grouped tools for extension capabilities that were not available through the ABAP FS MCP surface.

Area	Capabilities
Connections	Multiple SAP profiles, lazy login, system metadata, ADT discovery export
Repository reads	Search, metadata, source ranges, batch reads, URI reads, source search, enhancements
Semantic services	Completion, definition lookup, quick-fix discovery, SAP formatter preview
Source writes	Exact source replacement, syntax diagnostics, activation, text elements
Refactoring	Rename, package move, extract method, quick-fix application, formatting, deletion
Quality	ABAP Unit, ATC, diagnostics, test-include creation
Transports	List, details, objects, compare, create, release, delete, owner/user management, object resolution
Versions	Active revision history, revision comparison, inactive source, guarded revision restore
abapGit	Repository list, remote information, create, pull, unlink, stage, push, check, branch switch
RAP	Availability, paged schema, defaults, validation, preview, generation, service binding details and publication
Runtime	Debugger, breakpoints, stack, variables, dumps, traces, heartbeat checks
Cross-system	Source comparison across configured SAP systems
Dependency analysis	Bounded where-used dependency graph
SAP GUI integration	Validated WebGUI transaction URL generation and optional local launch
Data	Read-only ADT SQL queries with bounded or file-based output
Artifacts	Mermaid validation/viewer and DOCX test documentation

The eight grouped extension tools are:

• inspect_abap_code
• refactor_abap_code
• manage_abapgit
• manage_rap_generator
• manage_abap_versions
• compare_abap_systems
• get_abap_dependency_graph
• run_sap_transaction

Grouping related actions keeps the tool-schema footprint lower than exposing every operation as a separate MCP tool.

Prerequisites

Ask your SAP administrator for:

• The SAP HTTPS base URL, for example https://sap-dev.company.com
• The three-digit SAP client number
• Your SAP user name
• ADT development permissions required by the operations you intend to use
• Confirmation that /sap/bc/adt and Basic Auth are enabled

Your machine needs:

• Node.js 20 or later
• Codex or Claude Code
• Network or VPN access to SAP
• npm registry access to install the public package

Verify Node.js first:

node --version

Quick start on Windows

1. Add an SAP profile

The following profile permits writes only to two dedicated packages. Use your real values and keep production profiles read-only.

npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 profile add DEV100 `
  --url "https://sap-dev.company.com" `
  --client 100 `
  --username "DEV_USER" `
  --environment development `
  --packages "Z_MCP_TEST,Z_MCP_TEST2"

PowerShell also accepts the command on one line. The profile ID DEV100 is a local alias.

Omit --packages for a read-only profile. An empty package allowlist denies every repository write.

2. Store the SAP password

npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 auth login DEV100

The password is entered without echo and stored with Windows DPAPI. It is never written to the profile file.

3. Verify ADT connectivity

npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 doctor DEV100

A successful response contains "ok": true.

4. Register the MCP server

Codex CLI:

codex mcp add sap-abap -- npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 serve --profile DEV100

Claude Code:

claude mcp add --transport stdio --scope user sap-abap -- npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 serve --profile DEV100

Restart the client after registration. Use codex mcp list, claude mcp get sap-abap, or the client's /mcp command to verify the connection.

5. Start with read-only requests

List the configured SAP systems and verify DEV100.
Find class ZCL_DEMO in DEV100 and read its RUN method.
Run syntax diagnostics and show a formatter preview without changing the source.
Build a depth-1 dependency graph for ZCL_DEMO.

Quick start on macOS

Use npx instead of npx.cmd:

npx -y @coaspe/sap-abap-mcp@0.3.0 profile add DEV100 \
  --url "https://sap-dev.company.com" \
  --client 100 \
  --username "DEV_USER" \
  --environment development \
  --packages "Z_MCP_TEST,Z_MCP_TEST2"

npx -y @coaspe/sap-abap-mcp@0.3.0 auth login DEV100
npx -y @coaspe/sap-abap-mcp@0.3.0 doctor DEV100
codex mcp add sap-abap -- npx -y @coaspe/sap-abap-mcp@0.3.0 serve --profile DEV100

SAP passwords are stored in macOS Keychain.

Codex desktop setup

If the codex command is not available, add a stdio MCP server in Codex settings:

• Name: sap-abap
• Command on Windows: npx.cmd
• Command on macOS: npx
• Arguments:

-y
@coaspe/sap-abap-mcp@0.3.0
serve
--profile
DEV100

Multiple SAP systems

Create one profile per SAP client, for example DEV100, QAS200, and PRD100. To expose all profiles through one MCP server, register serve without --profile:

codex mcp add sap-abap -- npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 serve

Every SAP-facing tool requires an explicit connectionId, which prevents accidental cross-system routing. Cross-system comparison requires the same object to exist in both selected profiles.

abapGit credentials

Public repositories require no additional setup. Store credentials for each private repository URL separately:

npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 abapgit auth login DEV100 `
  --repository-url "https://github.example.com/team/repo.git" `
  --username "GIT_USER"

Status and removal:

npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 abapgit auth status DEV100 `
  --repository-url "https://github.example.com/team/repo.git"

npx.cmd -y @coaspe/sap-abap-mcp@0.3.0 abapgit auth logout DEV100 `
  --repository-url "https://github.example.com/team/repo.git"

Credentials are selected by canonical repository URL so credentials for one remote cannot be sent to another. Passwords and tokens are not accepted as MCP tool arguments, and credentials embedded in a repository URL are rejected.

Write-safety model

Repository-changing operations enforce these rules:

• Profiles marked production reject writes.
• The target package must be present in the profile's allowedPackages list.
• Packages other than $TMP require a transport request.
• Exact source replacement reads the current source, obtains an SAP lock, rechecks it under the lock, writes, runs syntax diagnostics, optionally activates, and unlocks.
• Rename, package move, method extraction, quick-fix application, formatting, deletion, and revision restore use a preview plan.
• Preview plans expire after ten minutes and require the exact returned confirmation value.
• Execution re-runs the SAP preview or source-state check and rejects stale plans.
• Multi-object quick-fixes perform syntax preflight and attempt rollback if a later write fails.
• RAP generation performs initial validation, content validation, and dry-run preview immediately before generation.
• abapGit push accepts only a fresh SAP staging snapshot and requires explicit object selection or stageAll=true.
• SAP transaction parameters use a restricted character set and are passed to the OS launcher as argument-array values rather than shell text.
• ADT SQL accepts only SELECT and WITH statements.

Transport release and deletion can be irreversible. Use a dedicated transport and verify the exact confirmation value before executing either action.

Token-efficient operation

The server is designed to keep model context usage bounded without removing useful data:

• Related operations are grouped into action-based tools.
• The complete 50-tool schema is kept below a 64 KiB automated guardrail.
• Source, search, SQL, ATC, dump, trace, transport, version, Git, and RAP schema responses are paged or summarized.
• Unified diffs are limited by both line count and byte size.
• Large source responses are bounded by an inline byte budget.
• Discovery data and large download manifests can be exported to local files.
• Compact JSON is returned without pretty-print whitespace.

Continue paged responses with fields such as nextStartIndex, nextLine, nextRowStart, and nextContentOffset.

Hosts without automatic tool search can register only selected toolsets:

sap-abap-mcp serve --profile DEV100 --toolsets core,write,analysis

Available toolsets are core, write, analysis, debug, operations, artifacts, and all. The default is all.

Real SAP acceptance testing

Run acceptance tests first against a development system and dedicated packages, objects, transports, repositories, and RAP artifacts.

Recommended order:

1. Connection, discovery, repository reads, semantic reads, versions, transports, and URL-only transaction generation.
2. Create a dedicated test class and verify source write, diagnostics, activation, formatter, quick-fix, rename, extract method, inactive source, restore, package move, and guarded deletion.
3. Test transport mutations only with a disposable transport.
4. Test abapGit only with a disposable remote repository.
5. Run RAP validation and preview before approving generation or service publication.

When reporting a failure, preserve the MCP error code, HTTP status, ADT endpoint, and SAP response text. Do not retry failed ADT operations with guessed parameter variants.

CLI reference

profile add <id> --url <url> --client <nnn> [--language EN]
    [--environment development|quality|production]
    [--username <user>] [--packages ZPKG1,ZPKG2]
profile list
profile remove <id>

auth login <id> [--username <user>] [--password-stdin]
auth status <id>
auth logout <id>

abapgit auth login <id> --repository-url <url> --username <user> [--password-stdin]
abapgit auth status <id> --repository-url <url>
abapgit auth logout <id> --repository-url <url>

doctor <id> [--include-components]
serve [--profile <id>] [--toolsets core,write,analysis,debug,operations,artifacts|all]

Removing a profile also removes its SAP password and stored abapGit credential vault.

Troubleshooting

Problem	Check
node is not found	Install Node.js 20 or later and reopen the terminal.
npm cannot download the package	Check internet access, proxy configuration, and npm registry policy.
PROFILE_NOT_FOUND	Run profile add again and verify the profile ID.
SAP login fails	Verify URL, client, username, password, VPN, Basic Auth, and ADT activation.
Certificate or connection error	Check the corporate CA, proxy, VPN, and SAP HTTPS endpoint.
Tools are missing	Confirm that the MCP client uses version 0.3.0, restart it, and inspect /mcp.
Writes return PACKAGE_NOT_ALLOWED	Add only the dedicated development package to --packages.
Writes return TRANSPORT_REQUIRED	Supply an open transport for non-local packages.
RAP generator is unavailable	The SAP release or installed components may not expose the RAP generator endpoints.
Private Git access fails	Store credentials for the exact canonical repository URL.

SSO-only or MFA-only SAP systems are not supported by this release. Ask the SAP administrator whether Basic Auth can be enabled for the ADT endpoint.

Local development

npm install
npm run check
npm audit --omit=dev
npm pack --dry-run

Register the current local build for pre-release testing:

npm run build
codex mcp add sap-abap-local -- node "/absolute/path/to/sap-abap-mcp/dist/src/index.js" serve --profile DEV100

The compatibility and toolset manifest is maintained in src/compat/abap-fs-tools.ts. ADT wrapper contract tests are in test/sap-client-contract.test.ts, and end-to-end in-memory MCP tests are in test/integration.test.ts.

Detailed Windows guide

See docs/localhost-mcp-end-to-end.md for the multi-system Windows setup, lifecycle, security model, and operational checklist.