# Gmail MCP Server

A Model Context Protocol (MCP) server implementation for Gmail integration, enabling AI assistants to interact with Gmail through a standardized interface.

## Features

- **Email Operations**
  - List and search emails with advanced filtering
  - Read email content with attachments
  - Send emails with attachments
  - Draft support (coming soon)
  - Reply/Forward support (coming soon)

- **Label Management**
  - List all labels
  - Create new labels
  - Update existing labels
  - Delete labels

- **Authentication**
  - Secure OAuth2 authentication
  - Automatic token refresh
  - Token persistence

## Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/gmail-mcp.git
cd gmail-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Set up Google Cloud Project:
   - Go to [Google Cloud Console](https://console.cloud.google.com)
   - Create a new project
   - Enable Gmail API
   - Configure OAuth consent screen
   - Create OAuth credentials
   - Download credentials as `gcp-oauth.keys.json`

4. Configure the project:
   - Place `gcp-oauth.keys.json` in the project root directory
   - Run the authentication server:
```bash
npm run auth
```

5. Build the project:
```bash
npm run build
```

## Usage

### Starting the Server

```bash
npm start
```

The server runs on stdio, making it compatible with MCP clients.

### Available Tools

#### 1. List Emails
```json
{
  "name": "list-emails",
  "arguments": {
    "maxResults": 10,
    "labelIds": ["INBOX"],
    "query": "is:unread"
  }
}
```

#### 2. Read Email
```json
{
  "name": "read-email",
  "arguments": {
    "id": "message-id",
    "format": "full"
  }
}
```

#### 3. Send Email
```json
{
  "name": "send-email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello",
    "body": "Message content",
    "attachments": ["/path/to/file.pdf"]
  }
}
```

#### 4. Search Emails
```json
{
  "name": "search-emails",
  "arguments": {
    "query": "from:sender@example.com",
    "maxResults": 5
  }
}
```

#### 5. Manage Labels
```json
{
  "name": "manage-labels",
  "arguments": {
    "action": "create",
    "name": "MyNewLabel"
  }
}
```

## Configuration

### Environment Variables

- `GMAIL_MCP_DEBUG`: Enable debug logging (default: false)
- `GMAIL_MCP_TOKEN_PATH`: Custom path for token storage
- `GMAIL_MCP_KEYS_PATH`: Custom path for OAuth keys file

### OAuth Credentials

The OAuth credentials file (`gcp-oauth.keys.json`) should be structured as:
```json
{
  "installed": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "redirect_uris": ["http://localhost:3000/oauth2callback"]
  }
}
```

## Development

### Running Tests

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch
```

### Building

```bash
# Build once
npm run build

# Build in watch mode
npm run dev
```

## Error Handling

The server handles various error scenarios:

- Authentication failures
- Rate limiting
- Invalid parameters
- Network issues
- Permission errors

Errors are returned in a standardized format with appropriate HTTP status codes.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Google Gmail API
- Model Context Protocol
- Contributors and maintainers

## Support

For support, please open an issue in the GitHub repository or contact the maintainers.