# Gmail MCP Server (FastAPI + Claude Desktop)

This project is a minimal Gmail **MCP server** built with FastAPI. It exposes a `/send-email/` HTTP endpoint and an MCP tool that can be called from MCP‑aware clients like Claude Desktop, so you can send real Gmail emails just by chatting with an AI assistant.

The flow is:

1. FastAPI app provides a `POST /send-email/` endpoint that sends email via the Gmail API.
2. `fastapi-mcp` wraps the app and exposes an MCP endpoint at `/mcp`.
3. Claude Desktop connects to the MCP server and calls the email tool when you ask it to send an email.

---

## 1. Project structure

Key files:

- `mcp_server.py` – FastAPI app with `/send-email/` and MCP wrapper.  
- `send_email.py` – Gmail API helper functions (OAuth, MIME message creation, sending).  
- `test_gmail_auth.py` – One‑time script to perform Gmail OAuth and create `token.json`.  
- `requirements.txt` – Python dependencies.  

**Not in Git (must be provided by each user):**

- `credentials.json` – Google OAuth client secrets downloaded from Google Cloud.  
- `token.json` – Gmail access/refresh tokens generated locally after you run `test_gmail_auth.py`.  

---

## 2. Prerequisites

Before you start, install:

- **Python 3.11+**  
- **Node.js** (for `npx` – used by Claude Desktop to run the MCP bridge)  
- **Claude Desktop** (latest version from Anthropic’s website)  
- A Google account with access to Gmail  

Clone the repo:
git clone https://github.com/TushaarKD/Kalpesh_MCP_Project.git
cd Kalpesh_MCP_Project


---

## 3. Set up Python environment

Create and activate a virtual environment:

python -m venv venv
.\venv\Scripts\Activate.ps1


Install dependencies:
pip install -r requirements.txt

This installs FastAPI, Uvicorn, Gmail API libraries, `fastapi-mcp`, etc.

---

## 4. Enable Gmail API and get credentials

1. Go to the **Google Cloud Console** and create a project (or use an existing one).  
2. In **APIs & Services → Library**, enable the **Gmail API** for your project.  
3. In **APIs & Services → Credentials**, create credentials:  
   - Type: **OAuth client ID**  
   - Application type: **Desktop app**  
4. Download the `credentials.json` file and place it in the **root** of this project (same folder as `mcp_server.py`).  
5. Make sure `credentials.json` is **not** committed to Git; it is in `.gitignore`.

---

## 5. Run Gmail OAuth once (`test_gmail_auth.py`)

With the venv active and `credentials.json` in place:

python test_gmail_auth.py


What this does:

- If `token.json` does not exist, it opens a browser window for Google login and consent.  
- After you approve access, it saves `token.json` in the project root.  
- Subsequent runs reuse or refresh this token without asking you to log in again.

Both `credentials.json` and `token.json` are local to your machine and should never be committed.

---

## 6. Start the Gmail MCP server

Start the FastAPI + MCP server:

uvicorn mcp_server:app --reload


By default this runs on `http://127.0.0.1:8000`.

### 6.1 Test the HTTP API (optional but recommended)

Open Swagger UI:

- Go to `http://localhost:8000/docs` in your browser.  
- Find `POST /send-email/`.  
- Click **Try it out** and use a JSON body like:

{
"to_email": "your-recipient@example.com",
"subject": "MCP Gmail test",
"body": "Hello from the Gmail MCP FastAPI server!"
}


Click **Execute**. You should see a success response and receive an email at the target address.

You can do the same from `curl`:

curl -X POST "http://127.0.0.1:8000/send-email/"
-H "Content-Type: application/json"
-d '{
"to_email": "your-recipient@example.com",
"subject": "MCP Gmail test via curl",
"body": "Hello from the Gmail MCP FastAPI server (curl)."
}'



---

## 7. MCP endpoint

The MCP server is exposed at:

http://localhost:8000/mcp


If you open that URL in a browser, you will see a JSON‑RPC error like:

{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Not Acceptable: Client must accept text/event-stream"}}


This is expected. MCP over HTTP uses **Server‑Sent Events**, so it requires special headers. MCP clients (like Claude Desktop) handle this for you.

---

## 8. Connect to Claude Desktop

Claude Desktop needs a **local MCP process** that speaks MCP over stdio. We use a small bridge called `mcp-remote` (run via `npx`) which forwards between Claude Desktop and your HTTP MCP server.

### 8.1 Install Node.js

If you don’t have Node.js, install the latest LTS from the official website. This gives you `npm` and `npx`.

### 8.2 Edit `claude_desktop_config.json`

Claude Desktop stores its config in `claude_desktop_config.json`. On Windows it is typically located at:

C:\Users<YourUser>\AppData\Roaming\Claude\claude_desktop_config.json


In Claude Desktop:

1. Open **Settings → Developer → Edit Config** to open this file.  
2. Add the following block under `"mcpServers"` (merge with existing content if needed):

{
"mcpServers": {
"gmail-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp",
"--transport",
"http-only"
]
}
}
}



- `gmail-mcp` is the name of this MCP server as seen by Claude.  
- `command` and `args` start a local bridge process that connects Claude Desktop to your HTTP MCP endpoint.

Save the file.

### 8.3 Restart Claude Desktop

1. Quit Claude Desktop completely (including tray icon).  
2. Start Claude Desktop again so it reloads the config.  
3. Ensure your FastAPI server is still running (`uvicorn mcp_server:app --reload`).  

In a new chat, Claude should now be able to use the `gmail-mcp` server.

---

## 9. Using the Gmail MCP tool from Claude

With everything running:

1. Open a new Claude Desktop chat.  
2. Ask something like:

> “Use the gmail-mcp server to send an email to `your-recipient@example.com` with subject `Test from Claude MCP` and body `Hello from my local Gmail MCP server`.”

Claude will:

- Discover the `gmail-mcp` tools.  
- Call the tool that maps to `POST /send-email/` with `to_email`, `subject`, and `body`.  
- Your FastAPI logs should show the email being sent.  
- You should receive the email at the recipient address.

---

## 10. Security notes

- **Do not commit** `credentials.json` or `token.json` to Git.  
- Only run this server on your own machine or in a secure environment; it has the power to send email from your Gmail account.  
- For demos, use a dedicated Gmail account if possible.