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

---

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

Tool	Purpose
gmail_status	Check whether Gmail credentials and token are available
gmail_list_recent	List recent inbox messages
gmail_search	Search Gmail using Gmail query syntax
gmail_read_message	Read one message by ID
gmail_create_draft	Create a Gmail draft
gmail_send_email	Send an email when enabled

Examples of Gmail search queries:

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

SAP

Tool	Purpose
sap_status	Show safe SAP configuration status
sap_test_connection	Test the service connection
sap_list_entities	Read an OData entity set
sap_get_entity	Read one entity by OData key
sap_safe_get	Perform a restricted GET request
sap_create_entity	Create a record when enabled
sap_update_entity	Update a record when enabled

---

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.