# Generic Gmail & Google Docs MCP Server

A Model Context Protocol (MCP) server that exposes Gmail and Google Docs capabilities to any MCP-compatible AI agent or client.

## Features

- **Agent-Agnostic**: Works with Cursor, Claude Desktop, and other MCP clients.
- **Gmail**: Create drafts (`gmail_draft`) and send emails (`gmail_send`).
- **Google Docs**: Append text to existing documents (`google_docs_append`).
- **Secure**: Uses OAuth 2.0. Secrets and tokens are never exposed.
- **Informative Errors**: Actionable error messages for AI agents.

## Setup Instructions

### 1. Google Cloud Project Setup
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project.
3. Enable the following APIs:
   - Gmail API
   - Google Docs API
4. Go to **OAuth consent screen** and configure it (External or Internal).
5. Add the following scopes:
   - `https://www.googleapis.com/auth/gmail.compose`
   - `https://www.googleapis.com/auth/documents`
6. Go to **Credentials** > **Create Credentials** > **OAuth client ID**.
7. Choose **Desktop app** (or Web application if you prefer, but ensure the redirect URI matches).
8. Copy the **Client ID** and **Client Secret**.

### 2. Local Setup
1. Clone the repository and run `npm install`.
2. Create a `.env` file based on `.env.example`:
   ```env
   GOOGLE_CLIENT_ID=your_client_id
   GOOGLE_CLIENT_SECRET=your_client_secret
   GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback
   GOOGLE_TOKEN_PATH=./data/google-token.json
   ```

### 3. Authentication
Run the authentication script to get your OAuth token:
```bash
npm run auth
```
Visit the URL, authorize the app, and paste the code back into the terminal. The token will be saved to `./data/google-token.json`.

### 4. Build
```bash
npm run build
```

## MCP Client Configuration

### Cursor
Add the following to your Cursor MCP configuration:
```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-google-server/dist/index.js"]
    }
  }
}
```

### Claude Desktop
Add the following to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-google-server/dist/index.js"]
    }
  }
}
```

## Development
- `npm run dev`: Run with tsx (STDIO)
- `npm run test`: Run tests with Vitest
- `npm run lint`: Run ESLint