# 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

```text
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.

```powershell
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:

```powershell
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:

```text
credentials/credentials.json
```

### Generate the Gmail token

```powershell
python scripts/gmail_auth.py
```

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

```text
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:

```env
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:

```env
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:

```env
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:

```text
/sap/opu/odata/sap/API_BUSINESS_PARTNER
/sap/opu/odata/sap/API_SALES_ORDER_SRV
```

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

```text
A_BusinessPartner
A_SalesOrder
A_Product
```

---

## 5. Test connections

```powershell
python scripts/test_connections.py
```

This checks configuration, Gmail authentication, and SAP connectivity.

---

## 6. Run the MCP server

```powershell
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:

```json
{
  "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:

```text
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:

```env
ALLOW_GMAIL_SEND=false
ALLOW_SAP_WRITE=false
```

To enable them:

```env
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

```powershell
pytest -q
```

---

## 12. Common errors

### `credentials.json was not found`

Put the downloaded Desktop OAuth JSON file at:

```text
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:

```powershell
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:

```env
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.