Metadata-Version: 2.4
Name: google-docs-mcp-server-ahmedlaminou
Version: 0.3.0
Summary: Stdio-first Google Docs and Drive MCP server with local browser OAuth and 100 tools
Project-URL: Homepage, https://github.com/AhmedLaminou/GoogleDocsMCPServer
Project-URL: Repository, https://github.com/AhmedLaminou/GoogleDocsMCPServer.git
Project-URL: Documentation, https://github.com/AhmedLaminou/GoogleDocsMCPServer/tree/main/docs
Project-URL: Issues, https://github.com/AhmedLaminou/GoogleDocsMCPServer/issues
Author-email: Ahmed Laminou Amadou <ahmedlaminouamadou@gmail.com>
License: MIT
License-File: LICENSE
Keywords: automation,google-docs,google-drive,mcp,vscode
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.111.0
Requires-Dist: google-api-python-client>=2.131.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: httplib2>=0.22.0
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: uvicorn>=0.30.1
Description-Content-Type: text/markdown

# Google Docs MCP Server

<!-- mcp-name: io.github.AhmedLaminou/google-docs-mcp-server -->

An open-source, stdio-first MCP server exposing **100 Google Docs and Drive tools**.

## User experience

End users do not need their own Google Cloud project. The published package uses this project's public Desktop OAuth client identity. Each user signs into their own Google account and stores a separate token only on their own machine.

```text
User prompt → AI client → local stdio MCP server
            → user's local OAuth token → user's Google Docs
```

The publisher does not receive user tokens or document content in local stdio mode.

## Install and authenticate

After publication:

```powershell
uvx --from google-docs-mcp-server-ahmedlaminou google-docs-mcp-auth login
```

The browser consent flow stores the token in:

- Windows: `%APPDATA%\GoogleDocsMCP\token.json`
- macOS: `~/Library/Application Support/GoogleDocsMCP/token.json`
- Linux: `~/.config/google-docs-mcp/token.json`

Useful commands:

```powershell
google-docs-mcp-auth status
google-docs-mcp-auth logout
```

Optional reliability settings:

```powershell
$env:GOOGLE_DOCS_MCP_HTTP_TIMEOUT = "60"
$env:GOOGLE_DOCS_MCP_API_RETRIES = "2"
```

## MCP client

```json
{
  "mcpServers": {
    "google-docs": {
      "command": "uvx",
      "args": [
        "--from",
        "google-docs-mcp-server-ahmedlaminou",
        "google-docs-mcp-server"
      ]
    }
  }
}
```

The VS Code extension registers this stdio server automatically.

## Permission profiles

The public/default profile requests:

- `documents` — read and edit Google Docs.
- `drive.file` — Drive operations for files created by or explicitly opened with the app.

This avoids the restricted full-Drive scope. Broad Drive listing/search and permission operations therefore only see files available to `drive.file`.

Self-hosters can intentionally opt into restricted full-Drive access:

```powershell
$env:GOOGLE_DOCS_MCP_SCOPE_PROFILE = "full"
google-docs-mcp-auth login --full-drive
```

## Developer setup

```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e .
google-docs-mcp-auth login
google-docs-mcp-server
```

Before a public release, the maintainer must create a Google OAuth client of type **Desktop app** and save its downloaded JSON as:

```text
google_docs_mcp_server/oauth_client.json
```

Desktop OAuth clients are public clients: their client identifier and nominal client secret cannot be kept confidential in a distributed/open-source desktop application. User refresh tokens remain private on each user's machine.

Self-hosters can instead put their own OAuth JSON at `%APPDATA%\GoogleDocsMCP\oauth_client.json` or set `GOOGLE_CREDENTIALS_FILE`.

## Optional hosted mode

FastAPI/SSE remains available:

```powershell
google-docs-mcp-web
```

It is not the default public architecture because true multi-user hosting requires per-user sessions and secure server-side token storage.

## Capabilities

- Document creation, rename, copy, trash/restore, metadata, folders, permissions,
  revisions, and multi-format export.
- Reading text, ranges, headings, footnotes, links, tables, images, structure,
  named ranges, and document tabs.
- Text, lists, links, images, headers, footers, footnotes, sections, tables,
  table rows/columns, and tab insertion.
- Rich formatting, comments/replies, named ranges, page setup, and raw batch updates.

Image generation remains provider-neutral: an AI client may generate an image
with any capable model or service, then pass its public URL to
`insert_external_image` or `replace_image`.

See [docs/TOOLS_REFERENCE.md](docs/TOOLS_REFERENCE.md).

## Verification

```powershell
python -m unittest discover -s tests -v
python -m compileall google_docs_mcp_server
python tests/smoke_stdio.py
```

## License

MIT. See [LICENSE](LICENSE).
