📊 XActions Google Sheets Plugin

Export scraped X/Twitter data directly to Google Sheets — no copy-paste, no CSV import.

Plugin: xactions-plugin-google-sheets
Author: nich (@nichxbt)

-----|-------------|----------|
| Service account (JSON string) | GOOGLE_SERVICE_ACCOUNT_KEY | Servers, CI/CD, automated exports |
| Service account (key file) | GOOGLE_SERVICE_ACCOUNT_KEY_FILE | Local development |
| OAuth2 access token | GOOGLE_ACCESS_TOKEN | Short-lived / user-facing apps |
| API key | GOOGLE_API_KEY | Read-only access to public sheets |

Recommended: Service account

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Create a Service Account → Generate a JSON key
3. Enable the Google Sheets API
4. Share your target spreadsheet with the service account email (...@...iam.gserviceaccount.com)
5. Set the env var:

export GOOGLE_SERVICE_ACCOUNT_KEY_FILE="./service-account-key.json"

3. Use it

import { exportToGoogleSheets } from 'xactions/plugins/google-sheets';

// After scraping followers...
const result = await exportToGoogleSheets(followers, {
  spreadsheetId: 'YOUR_SPREADSHEET_ID',  // from the Sheet URL
  sheetName: 'Followers',
  mode: 'append',  // 'append' | 'replace' | 'new-sheet'
});

console.log(`✅ Exported ${result.rowsWritten} rows → ${result.url}`);

🖥️ CLI Usage

All scrape commands now support --google-sheets:

# Scrape followers and push directly to Google Sheets
xactions followers @nichxbt --google-sheets YOUR_SPREADSHEET_ID --sheet-name Followers

# Scrape tweets and append to a sheet
xactions tweets @nichxbt -l 200 --google-sheets YOUR_SPREADSHEET_ID --sheet-name Tweets

# Replace instead of append
xactions following @nichxbt --google-sheets YOUR_SPREADSHEET_ID --sheet-mode replace

🤖 MCP Tools (AI Agents)

The plugin registers three MCP tools:

Example AI agent prompt:

"Scrape @nichxbt's followers and export them to my Google Sheet 1BxiM..."

🔌 REST API

When loaded as a plugin, these routes are available:

Example:

curl -X POST http://localhost:3000/api/plugins/xactions-plugin-google-sheets/export \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{"username": "nichxbt", "followers": 12500}],
    "spreadsheetId": "YOUR_ID",
    "sheetName": "Followers",
    "mode": "append"
  }'

📖 API Reference

exportToGoogleSheets(data, options)

Returns: { success, spreadsheetId, rowsWritten, columnsWritten, headers, url }

readFromGoogleSheets(options)

Returns: Object[] — array of objects keyed by header row

createSpreadsheet(options)

Returns: { spreadsheetId, url, title, sheetNames }