PaperClipAI/packages/google-sheets-mcp-server

Google Sheets MCP Server

First-party MCP server for Google Sheets API v4. It can run as a Paperclip local_stdio gallery connection or as a local Streamable HTTP server for Paperclip's remote_http connect-by-link flow.

Configuration

The server uses Google service-account credentials only. OAuth is intentionally not supported in v1.

Required:

• GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS: comma or newline separated spreadsheet IDs the server may access.
• One of:
  • GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON: inline service-account JSON, or a path to a service-account JSON file.
  • GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_PATH: path to a service-account JSON file.

Equivalent CLI flags are available for local stdio templates:

paperclip-google-sheets-mcp-server \
  --service-account-json-path /path/to/service-account.json \
  --allowed-spreadsheet-ids sheet_id_1,sheet_id_2

Share each allowed spreadsheet with the service account's client_email.

Paperclip local_stdio Test Path

Use the Google Sheets gallery app when you want Paperclip to supervise the server as a stdio MCP process:

1. Configure Paperclip's Google Sheets service account environment so the gallery marks Google Sheets as available. The service account JSON must be provided by GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON or GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_PATH.
2. Share every spreadsheet you want to test with the service account's client_email.
3. In Paperclip, open the tool app gallery, choose Google Sheets, and paste one or more Google Sheets links.
4. Save the app connection. Paperclip creates a local_stdio connection using the paperclip.google-sheets template and passes the selected spreadsheet IDs to this server as GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS.
5. Refresh the tool catalog and verify the Google Sheets tools appear for the connection.

In this path, the spreadsheet allowlist comes from the gallery wizard. Every tool call is still checked against the server-side allowlist before the server calls Google.

Paperclip remote_http Test Path

Use the HTTP binary when you want to exercise the same tools through Paperclip's remote_http gateway:

GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_PATH=/path/to/service-account.json \
GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS=sheet_id_1,sheet_id_2 \
GOOGLE_SHEETS_MCP_HOST=127.0.0.1 \
GOOGLE_SHEETS_MCP_PORT=8849 \
GOOGLE_SHEETS_MCP_TOKEN=local-test-token \
paperclip-google-sheets-mcp-http-server

The HTTP server prints the MCP endpoint on startup. With the values above, use:

http://127.0.0.1:8849/mcp

Then in Paperclip, choose the remote HTTP or "connect with a link" path, paste the /mcp URL, and configure the bearer token if GOOGLE_SHEETS_MCP_TOKEN is set. The HTTP server accepts the token only as an Authorization: Bearer <token> header.

HTTP configuration:

• GOOGLE_SHEETS_MCP_HOST: host to bind. Defaults to 127.0.0.1. If this is not a loopback host, GOOGLE_SHEETS_MCP_TOKEN is required and startup fails closed when the token is omitted.
• GOOGLE_SHEETS_MCP_PORT: port to bind. Defaults to 8849.
• PORT: platform-style port override. When set, it takes precedence over GOOGLE_SHEETS_MCP_PORT.
• GOOGLE_SHEETS_MCP_TOKEN: optional shared secret for the /mcp route. Omit only for loopback/local single-operator testing where no other process can reach the server.

The HTTP server reuses the same service-account and spreadsheet allowlist environment as stdio. In this phase, the HTTP spreadsheet allowlist is process-level configuration (GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS or GOOGLE_SHEETS_SPREADSHEET_IDS), not a per-connection Paperclip gallery wizard setting or shared multi-tenant policy. Treat this as a local/single-operator test path. Restart the HTTP process with a different allowlist when you need to test a different spreadsheet set.

Tools

• list_spreadsheets (read)
• get_spreadsheet_info (read)
• read_values (read)
• search_rows (read)
• append_rows (write)
• update_values (write)
• add_sheet_tab (write)
• clear_values (destructive)
• delete_rows (destructive)

Every tool that accepts a spreadsheet ID rejects IDs outside the configured allowlist before calling Google. list_spreadsheets lists only the allowlisted IDs.