INTEGRATION.md•3.34 kB
# Gmail MCP Server Integration Guide
This guide explains how to integrate the Gmail MCP Server with other projects.
## Essential Files for Integration
### Core Files (Required)
- `gmail_mcp_server.py` - Main MCP server implementation
- `requirements.txt` - Python dependencies
- `gcp-oauth.keys.json` - Your GCP OAuth credentials (create from example)
### Configuration Files (Optional)
- `mcp_config.json` - MCP client configuration template
- `setup.py` - Installation script
### Testing (Optional)
- `direct_test.py` - Simple functionality test
## Integration Steps
### 1. Copy Core Files
Copy these files to your project:
```bash
cp gmail_mcp_server.py /path/to/your/project/
cp requirements.txt /path/to/your/project/
cp gcp-oauth.keys.json.example /path/to/your/project/gcp-oauth.keys.json
# Edit gcp-oauth.keys.json with your actual credentials
```
### 2. Install Dependencies
```bash
pip install -r requirements.txt
```
### 3. Configure MCP Client
Add to your MCP client configuration:
```json
{
"mcpServers": {
"gmail": {
"command": "python",
"args": ["gmail_mcp_server.py"],
"cwd": "/path/to/your/project"
}
}
}
```
### 4. Test Integration
```bash
python direct_test.py
```
## Available Tools
The server provides these MCP tools:
- `authenticate_gmail` - OAuth2 authentication
- `list_emails` - List emails from inbox
- `read_email` - Read specific email
- `send_email` - Send emails
- `search_emails` - Search emails with Gmail syntax
- `mark_as_read` - Mark email as read
- `mark_as_unread` - Mark email as unread
## Usage Example
```python
# Example MCP client usage
import mcp.client.stdio as mcp_stdio
async def use_gmail_tools():
# Connect to server
client = await mcp_stdio.stdio_client()
# Authenticate
await client.call_tool("authenticate_gmail", {})
# Send email
await client.call_tool("send_email", {
"to": "recipient@example.com",
"subject": "Test Email",
"body": "Hello from MCP!"
})
# List emails
emails = await client.call_tool("list_emails", {"max_results": 10})
```
## Security Considerations
- Keep `gcp-oauth.keys.json` secure
- Don't commit credentials to version control
- The `token.pickle` file contains access tokens - keep it secure
- Use environment variables for sensitive data in production
## Troubleshooting
### Authentication Issues
- Verify `gcp-oauth.keys.json` is valid
- Check Gmail API is enabled in Google Cloud Console
- Ensure OAuth consent screen is configured
### Server Not Starting
- Check all dependencies are installed
- Verify Python version (3.8+ required)
- Check for port conflicts
### Tool Call Failures
- Ensure authentication completed successfully
- Check Gmail API quotas and limits
- Verify email addresses are valid
## Production Deployment
For production use:
1. **Environment Variables**: Store credentials in environment variables
2. **Process Management**: Use systemd, PM2, or similar
3. **Logging**: Add proper logging and monitoring
4. **Security**: Implement proper access controls
5. **Scaling**: Consider multiple server instances for high load
## Support
For integration issues:
1. Check the main README.md
2. Run `python direct_test.py` to verify functionality
3. Review Gmail API documentation
4. Check MCP protocol specifications