Gmail + SAP MCP Integration

A complete starter project that exposes Gmail and SAP OData operations as Model Context Protocol (MCP) tools.

What this project can do

Gmail tools

• Authenticate with Google OAuth 2.0

• Search emails using normal Gmail search syntax

• Read an email

• List recent inbox emails

• Create an email draft

• Send an email, disabled by default for safety

SAP tools

• Test the SAP connection

• Read an OData entity set

• Read a single OData entity

• Create an OData record, disabled by default

• Update an OData record, disabled by default

• Execute a safe raw GET request

• Run without a real SAP system using built-in mock data

MCP

• Runs as a standard stdio MCP server

• Can be connected to MCP-compatible clients

• Uses explicit environment flags for write operations

• Returns JSON-friendly tool results

Related MCP server: Gmail MCP Server

Project structure

gmail_sap_mcp_project/
├── app/
│   ├── config.py
│   ├── server.py
│   ├── gmail_client.py
│   ├── sap_client.py
│   ├── models.py
│   └── utils.py
├── scripts/
│   ├── gmail_auth.py
│   └── test_connections.py
├── tests/
│   ├── test_sap_client.py
│   └── test_utils.py
├── credentials/
│   └── .gitkeep
├── .env.example
├── .gitignore
├── mcp-config.example.json
├── pyproject.toml
├── requirements.txt
├── run_server.py
└── README.md

1. Prerequisites

Install:

• Python 3.11 or 3.12

• A Google Cloud project

• Gmail API enabled in Google Cloud

• OAuth Desktop App credentials

• Optional: SAP S/4HANA, SAP Gateway, SAP Business One service layer, or another SAP OData endpoint

This project does not require a Google service-account key. Gmail user data is accessed using OAuth user consent.

2. Setup on Windows PowerShell

Open PowerShell in the project folder.

py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item .env.example .env

If PowerShell blocks activation:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1

3. Configure Gmail

Google Cloud steps

1. Create or select a Google Cloud project.

2. Open APIs & Services → Library.

3. Enable Gmail API.

4. Open Google Auth Platform.

5. Configure the consent screen.

6. Add your Gmail address as a test user while the app is in testing.

7. Open Clients → Create Client.

8. Select Desktop app.

9. Download the JSON file.

10. Rename it to credentials.json.

11. Put it here:

credentials/credentials.json

Generate the Gmail token

python scripts/gmail_auth.py

A browser window will ask you to approve Gmail access. The generated token is stored at:

credentials/token.json

The default scopes allow reading Gmail, creating drafts, and sending mail. To use read-only access, change GMAIL_SCOPES in .env, delete credentials/token.json, and authenticate again.

4. Configure SAP

Copy .env.example to .env.

Option A: Start in mock mode

Keep:

SAP_MOCK_MODE=true

No real SAP credentials are needed. This is the best way to learn and test the MCP integration.

Option B: Use a real SAP OData service

Example configuration:

SAP_MOCK_MODE=false
SAP_BASE_URL=https://your-sap-host.example.com
SAP_ODATA_PATH=/sap/opu/odata/sap/API_BUSINESS_PARTNER
SAP_AUTH_TYPE=basic
SAP_USERNAME=your_username
SAP_PASSWORD=your_password
SAP_VERIFY_SSL=true

For bearer-token authentication:

SAP_AUTH_TYPE=bearer
SAP_BEARER_TOKEN=your_access_token

SAP_ODATA_PATH should point to the service root, not an individual entity set.

Examples:

/sap/opu/odata/sap/API_BUSINESS_PARTNER
/sap/opu/odata/sap/API_SALES_ORDER_SRV

Entity-set names vary by SAP service, such as:

A_BusinessPartner
A_SalesOrder
A_Product

5. Test connections

python scripts/test_connections.py

This checks configuration, Gmail authentication, and SAP connectivity.

6. Run the MCP server

python run_server.py

Because this is a stdio MCP server, it waits for an MCP client and normally does not show a web page.

Important: do not add print() statements to the MCP server's standard output. Logging goes to standard error.

7. Connect it to an MCP client

Use the absolute path to your Python executable and project folder.

Example MCP configuration:

{
  "mcpServers": {
    "gmail-sap": {
      "command": "C:\\absolute\\path\\gmail_sap_mcp_project\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\absolute\\path\\gmail_sap_mcp_project\\run_server.py"
      ],
      "cwd": "C:\\absolute\\path\\gmail_sap_mcp_project",
      "env": {
        "ENV_FILE": "C:\\absolute\\path\\gmail_sap_mcp_project\\.env"
      }
    }
  }
}

A ready template is included as mcp-config.example.json.

Restart your MCP client after changing its configuration.

8. Available MCP tools

Gmail

Examples of Gmail search queries:

from:manager@example.com newer_than:7d
subject:invoice has:attachment
is:unread in:inbox

SAP

9. Safety settings

Write operations are disabled by default:

ALLOW_GMAIL_SEND=false
ALLOW_SAP_WRITE=false

To enable them:

ALLOW_GMAIL_SEND=true
ALLOW_SAP_WRITE=true

Restart the MCP server after changing .env.

For production:

• Use a secrets manager rather than committing secrets.

• Use least-privilege Google scopes.

• Use a dedicated SAP communication user.

• Restrict SAP authorizations to required business objects.

• Keep TLS verification enabled.

• Add approval steps before sending email or changing SAP data.

• Log tool invocation metadata, but never log tokens or passwords.

10. Example real-life workflow

A manager asks:

Find unread supplier emails received this week, extract the supplier numbers, and check those suppliers in SAP.

The AI client can:

1. Call gmail_search with is:unread newer_than:7d supplier.

2. Read selected messages using gmail_read_message.

3. Extract supplier IDs.

4. Query the relevant SAP entity set using sap_list_entities.

5. Present a combined summary.

A write workflow could draft a reply with gmail_create_draft. Sending remains blocked unless explicitly enabled.

11. Run tests

pytest -q

12. Common errors

credentials.json was not found

Put the downloaded Desktop OAuth JSON file at:

credentials/credentials.json

Google says the app is not verified

For development, keep the app in testing and add your Gmail account as a test user.

invalid_grant

Delete credentials/token.json and run:

python scripts/gmail_auth.py

SAP returns 401 or 403

Check the authentication method, username, password/token, communication arrangement, and SAP authorizations.

SAP returns 404

Confirm SAP_BASE_URL, SAP_ODATA_PATH, and entity-set spelling. Open the service $metadata endpoint in a browser or API client.

SSL certificate error

Prefer installing the proper corporate CA certificate. Only for local testing, set:

SAP_VERIFY_SSL=false

Do not disable TLS verification in production.

Notes

MCP connects the AI client to tools. It does not automatically decide your SAP business rules, approve transactions, or bypass Google/SAP permissions.