Metadata-Version: 2.4
Name: mcp-google-drive
Version: 0.1.0
Summary: A Parafin internal MCP server for interacting with Google Drive (Sheets/Docs).
Requires-Python: >=3.12
Requires-Dist: google-api-python-client>=2.194.0
Requires-Dist: google-auth-oauthlib>=1.3.1
Requires-Dist: google-auth>=2.0.0
Requires-Dist: mcp[cli]==1.27.0
Description-Content-Type: text/markdown

# mcp-google-drive

Parafin internal MCP server for Google Drive, Sheets, and Docs. Built with FastMCP and distributed via Claude Desktop (`.mcpb`) for accounting and Claude Code (CodeArtifact) for developers.

## Auth

On first run, a browser window opens for Google OAuth. Sign in with your `@parafin.com` account. A token is saved to `~/.config/mcp-google-drive/token.json` and silently refreshed on subsequent runs.

**Prerequisites:** Place `credentials.json` (obtain from #llm in Slack) at:
```
~/.config/mcp-google-drive/credentials.json
```

## Setup (Developers)

```bash
# One-time install from CodeArtifact
export CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
  --domain parafin --domain-owner <AWS_ACCOUNT_ID> \
  --query authorizationToken --output text)

export UV_INDEX_URL="https://aws:${CODEARTIFACT_AUTH_TOKEN}@parafin-<AWS_ACCOUNT_ID>.d.codeartifact.us-east-1.amazonaws.com/pypi/parafin/simple/"

uvx --index-url "${UV_INDEX_URL}" mcp-google-drive

# Register with Claude Code
claude mcp add google-drive -- uvx mcp-google-drive
```

## Local Development

```bash
claude mcp add google-drive -- uv run --directory /path/to/mcp-google-drive mcp-google-drive
```

---

## Tools

### Google Sheets — Read

| Tool | Description |
|------|-------------|
| `get_sheet_data` | Get cell values from a sheet, optionally including formatting metadata |
| `get_sheet_formulas` | Get raw formulas from a sheet |
| `list_sheets` | List all sheet tabs in a spreadsheet |
| `list_spreadsheets` | List spreadsheets in a Drive folder |
| `get_multiple_sheet_data` | Fetch data from multiple sheet ranges in one call |
| `get_multiple_spreadsheet_summary` | Summarize multiple spreadsheets (headers + first N rows) |
| `search_spreadsheets` | Search for spreadsheets by name or content |
| `find_in_spreadsheet` | Find cells containing a specific value across sheets |

### Google Sheets — Write / Create

| Tool | Description |
|------|-------------|
| `update_cells` | Write values to a cell range |
| `batch_update_cells` | Write to multiple ranges in one call |
| `add_rows` | Insert rows into a sheet |
| `add_columns` | Insert columns into a sheet |
| `copy_sheet` | Copy a sheet tab between spreadsheets |
| `rename_sheet` | Rename a sheet tab |
| `create_spreadsheet` | Create a new Google Spreadsheet |
| `create_sheet` | Add a new tab to an existing spreadsheet |
| `share_spreadsheet` | Share a spreadsheet with users by email and role |
| `batch_update` | Execute raw Sheets API batchUpdate requests |
| `add_chart` | Add a column, bar, line, area, pie, or scatter chart to a sheet |

### Google Drive — Read

| Tool | Description |
|------|-------------|
| `list_files` | List files, optionally filtered by folder and/or MIME type |
| `get_file_metadata` | Get metadata for a file (name, type, owners, modified date) |
| `search_files` | Search files using a full Drive query string |
| `list_folders` | List folders within a parent folder |
| `get_file_content` | Download raw text content of a file (CSV, TXT, etc.) |

### Google Drive — Write / Create

| Tool | Description |
|------|-------------|
| `create_folder` | Create a new folder |
| `move_file` | Move a file to a different folder |

### Google Docs — Read

| Tool | Description |
|------|-------------|
| `get_document` | Get the full plain text content of a Google Doc |
| `list_documents` | List Google Docs in Drive or a specific folder |

### Google Docs — Write / Create

| Tool | Description |
|------|-------------|
| `create_document` | Create a new Google Doc |
| `update_document` | Apply raw Docs API batchUpdate requests to a document |

---

## Permissions

Access control is enforced by [Formal.ai](https://www.joinformal.ai/) at the proxy layer. The server exposes the full tool surface — Formal policies determine what each user can actually do. The GCP OAuth application is scoped to `@parafin.com` accounts only.

---

## Credential Files

| File | Purpose | Source |
|------|---------|--------|
| `~/.config/mcp-google-drive/credentials.json` | OAuth client ID/secret | Shared via #llm or IT |
| `~/.config/mcp-google-drive/token.json` | User access/refresh token | Generated on first run |

Neither file should ever be committed to version control.
