API.md•14.8 kB
# API Documentation
This document provides comprehensive documentation for all MCP tools exposed by the Google Drive MCP Server.
## Table of Contents
1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Tool Reference](#tool-reference)
4. [Error Handling](#error-handling)
5. [Rate Limiting](#rate-limiting)
6. [Best Practices](#best-practices)
## Overview
The Google Drive MCP Server exposes 6 main tools through the Model Context Protocol (MCP):
- `drive_search_files` - Search for files on Google Drive
- `drive_get_file` - Retrieve complete file information and content
- `drive_get_content_chunk` - Extract specific portions of file content
- `drive_get_file_metadata` - Get detailed file metadata and permissions
- `drive_list_folder` - List contents of a folder
- `drive_get_comments` - Retrieve comments from a file
All tools return JSON responses and support various parameters for filtering and customization.
## Authentication
The server handles Google OAuth 2.0 authentication automatically. Ensure you have:
- Valid Google Client ID and Secret
- Proper OAuth consent screen configuration
- Required scopes: `drive.readonly` and `documents.readonly`
## Tool Reference
### drive_search_files
Search for files on Google Drive with various filters and options.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query text |
| `fileType` | string[] | No | Array of MIME types to filter by |
| `folderId` | string | No | Limit search to specific folder |
| `modifiedAfter` | string | No | ISO date string (YYYY-MM-DD) |
| `modifiedBefore` | string | No | ISO date string (YYYY-MM-DD) |
| `owner` | string | No | Filter by file owner |
| `limit` | number | No | Maximum number of results (default: 20) |
| `orderBy` | string | No | Sort order: 'name', 'modifiedTime', 'createdTime' |
**Response:**
```json
{
"files": [
{
"id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"name": "Quarterly Report.pdf",
"mimeType": "application/pdf",
"size": 2048576,
"modifiedTime": "2024-01-15T10:30:00.000Z",
"createdTime": "2024-01-10T09:00:00.000Z",
"owners": [
{
"displayName": "John Doe",
"emailAddress": "john@example.com"
}
],
"webViewLink": "https://drive.google.com/file/d/...",
"parents": ["0BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"]
}
],
"totalCount": 1,
"hasMore": false
}
```
**Examples:**
```json
// Basic search
{
"name": "drive_search_files",
"arguments": {
"query": "presentation"
}
}
// Advanced search with filters
{
"name": "drive_search_files",
"arguments": {
"query": "quarterly report",
"fileType": ["application/pdf", "application/vnd.google-apps.document"],
"modifiedAfter": "2024-01-01",
"limit": 10,
"orderBy": "modifiedTime"
}
}
```
### drive_get_file
Retrieve complete file information and optionally include the full content.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Google Drive file ID |
| `includeContent` | boolean | No | Whether to include file content (default: true) |
**Response:**
```json
{
"id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"name": "Document.pdf",
"mimeType": "application/pdf",
"size": 1024000,
"content": "# Document Title\n\nThis is the content...",
"metadata": {
"wordCount": 1500,
"pageCount": 10,
"language": "en",
"headings": [
{
"level": 1,
"text": "Document Title",
"position": 0
}
],
"lastProcessed": "2024-01-15T10:30:00.000Z"
},
"modifiedTime": "2024-01-15T10:00:00.000Z",
"owners": [...],
"permissions": [...]
}
```
**Examples:**
```json
// Get file with content
{
"name": "drive_get_file",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"includeContent": true
}
}
// Get file metadata only
{
"name": "drive_get_file",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"includeContent": false
}
}
```
### drive_get_content_chunk
Extract specific portions of file content using various methods.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Google Drive file ID |
| `startChar` | number | No | Starting character position |
| `endChar` | number | No | Ending character position |
| `startPage` | number | No | Starting page number |
| `endPage` | number | No | Ending page number |
| `searchQuery` | string | No | Search for specific content |
| `contextLines` | number | No | Lines of context around search results |
**Response:**
```json
{
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"content": "Extracted content...",
"startPosition": 0,
"endPosition": 1000,
"totalLength": 50000,
"matches": [
{
"content": "Content around search term...",
"position": 1500,
"context": {
"before": "Previous context...",
"after": "Following context..."
}
}
]
}
```
**Examples:**
```json
// Get content by character range
{
"name": "drive_get_content_chunk",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"startChar": 0,
"endChar": 5000
}
}
// Get content by page range
{
"name": "drive_get_content_chunk",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"startPage": 1,
"endPage": 3
}
}
// Search for specific content
{
"name": "drive_get_content_chunk",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"searchQuery": "executive summary",
"contextLines": 3
}
}
```
### drive_get_file_metadata
Retrieve detailed metadata and permissions for a file.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Google Drive file ID |
| `includePermissions` | boolean | No | Include detailed permissions (default: false) |
**Response:**
```json
{
"id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"name": "Document.pdf",
"mimeType": "application/pdf",
"size": 1024000,
"modifiedTime": "2024-01-15T10:00:00.000Z",
"createdTime": "2024-01-10T09:00:00.000Z",
"owners": [
{
"displayName": "John Doe",
"emailAddress": "john@example.com",
"photoLink": "https://..."
}
],
"permissions": [
{
"id": "12345",
"type": "user",
"role": "owner",
"emailAddress": "john@example.com"
}
],
"parents": ["0BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"],
"webViewLink": "https://drive.google.com/file/d/...",
"webContentLink": "https://drive.google.com/uc?id=...",
"shared": true,
"starred": false,
"trashed": false,
"version": "12345",
"contentMetadata": {
"wordCount": 1500,
"pageCount": 10,
"language": "en"
}
}
```
**Examples:**
```json
// Basic metadata
{
"name": "drive_get_file_metadata",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
}
}
// Metadata with permissions
{
"name": "drive_get_file_metadata",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"includePermissions": true
}
}
```
### drive_list_folder
List the contents of a folder with optional filtering.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `folderId` | string | Yes | Google Drive folder ID |
| `fileType` | string[] | No | Filter by MIME types |
| `orderBy` | string | No | Sort order: 'name', 'modifiedTime', 'createdTime' |
| `limit` | number | No | Maximum number of results (default: 50) |
**Response:**
```json
{
"folderId": "0BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"folderName": "My Documents",
"files": [
{
"id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"name": "Document.pdf",
"mimeType": "application/pdf",
"size": 1024000,
"modifiedTime": "2024-01-15T10:00:00.000Z",
"isFolder": false
}
],
"totalCount": 1,
"hasMore": false
}
```
**Examples:**
```json
// List all files in folder
{
"name": "drive_list_folder",
"arguments": {
"folderId": "0BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
}
}
// List PDFs only, sorted by date
{
"name": "drive_list_folder",
"arguments": {
"folderId": "0BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"fileType": ["application/pdf"],
"orderBy": "modifiedTime",
"limit": 20
}
}
```
### drive_get_comments
Retrieve comments from a file (if available and accessible).
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Google Drive file ID |
| `limit` | number | No | Maximum number of comments (default: 50) |
| `includeReplies` | boolean | No | Include comment replies (default: true) |
**Response:**
```json
{
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"comments": [
{
"id": "comment123",
"content": "This section needs revision",
"author": {
"displayName": "Jane Smith",
"emailAddress": "jane@example.com"
},
"createdTime": "2024-01-15T14:30:00.000Z",
"modifiedTime": "2024-01-15T14:30:00.000Z",
"resolved": false,
"replies": [
{
"id": "reply456",
"content": "I'll update this today",
"author": {
"displayName": "John Doe",
"emailAddress": "john@example.com"
},
"createdTime": "2024-01-15T15:00:00.000Z"
}
]
}
],
"totalCount": 1,
"hasMore": false
}
```
**Examples:**
```json
// Get all comments
{
"name": "drive_get_comments",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
}
}
// Get recent comments without replies
{
"name": "drive_get_comments",
"arguments": {
"fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"limit": 10,
"includeReplies": false
}
}
```
## Error Handling
All tools return standardized error responses when issues occur:
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
"additionalInfo": "value"
},
"retryable": true,
"suggestedAction": "Please check your authentication and try again"
}
}
```
### Common Error Codes
| Code | Description | Retryable |
|------|-------------|-----------|
| `AUTHENTICATION_FAILED` | Invalid or expired credentials | No |
| `PERMISSION_DENIED` | Insufficient permissions for file/folder | No |
| `FILE_NOT_FOUND` | Requested file does not exist | No |
| `QUOTA_EXCEEDED` | API quota limit reached | Yes |
| `RATE_LIMITED` | Too many requests | Yes |
| `NETWORK_ERROR` | Network connectivity issues | Yes |
| `PROCESSING_ERROR` | File processing failed | No |
| `INVALID_PARAMETERS` | Invalid request parameters | No |
## Rate Limiting
The server implements rate limiting to comply with Google Drive API quotas:
- **Default Limits**: 1000 requests per 100 seconds per user
- **Retry Logic**: Automatic exponential backoff for rate-limited requests
- **Circuit Breaker**: Temporary suspension after repeated failures
### Best Practices for Rate Limiting
1. **Batch Operations**: Use search filters to reduce API calls
2. **Cache Utilization**: Leverage built-in caching for repeated requests
3. **Pagination**: Use `limit` parameters to control response size
4. **Error Handling**: Implement proper retry logic for rate-limited requests
## Best Practices
### Performance Optimization
1. **Use Specific Searches**: Include file type and date filters to reduce result sets
2. **Leverage Caching**: The server automatically caches content and metadata
3. **Chunk Large Files**: Use `drive_get_content_chunk` for files larger than 50MB
4. **Batch Metadata**: Get metadata separately from content for better performance
### Content Processing
1. **Check File Size**: Always check file size before processing large documents
2. **Use Search Queries**: Use `searchQuery` parameter to find specific content sections
3. **Page-based Extraction**: For PDFs, use page ranges instead of character ranges
4. **Context Lines**: Include context lines when searching for specific content
### Error Handling
1. **Implement Retries**: Use exponential backoff for retryable errors
2. **Check Permissions**: Verify file access before attempting content extraction
3. **Handle Large Files**: Implement chunking strategy for files exceeding limits
4. **Monitor Quotas**: Track API usage to avoid quota exhaustion
### Security
1. **Validate File IDs**: Always validate file IDs before processing
2. **Respect Permissions**: Honor Google Drive sharing and permission settings
3. **Secure Credentials**: Never expose OAuth credentials in client code
4. **Audit Access**: Monitor file access patterns for security compliance
## Examples and Workflows
### Common Workflow: Document Research
```javascript
// 1. Search for relevant documents
const searchResults = await client.callTool('drive_search_files', {
query: 'market research 2024',
fileType: ['application/pdf', 'application/vnd.google-apps.document'],
modifiedAfter: '2024-01-01',
limit: 10
});
// 2. Get metadata for each file
for (const file of searchResults.files) {
const metadata = await client.callTool('drive_get_file_metadata', {
fileId: file.id,
includePermissions: true
});
// 3. Extract relevant content sections
if (metadata.size < 50 * 1024 * 1024) { // 50MB limit
const content = await client.callTool('drive_get_content_chunk', {
fileId: file.id,
searchQuery: 'executive summary',
contextLines: 3
});
// Process content...
}
}
```
### Batch Processing Workflow
```javascript
// 1. List folder contents
const folderContents = await client.callTool('drive_list_folder', {
folderId: 'your-folder-id',
fileType: ['application/pdf'],
orderBy: 'modifiedTime'
});
// 2. Process each file
const results = [];
for (const file of folderContents.files) {
try {
const content = await client.callTool('drive_get_content_chunk', {
fileId: file.id,
startChar: 0,
endChar: 2000
});
results.push({
file: file.name,
preview: content.content.substring(0, 200)
});
} catch (error) {
console.error(`Error processing ${file.name}:`, error);
}
}
```
This API documentation provides comprehensive guidance for integrating with the Google Drive MCP Server. For additional examples and use cases, see the [Examples documentation](./EXAMPLES.md).