GoogleSheetsMCP - AgenticLedger Platform

Google Sheets MCP Server

Production-ready MCP server providing comprehensive Google Sheets integration for the AgenticLedger AI Agent Platform.

🚀 Features

• 26 Production-Ready Tools - Complete CRUD operations, formatting, charts, sheet management

• Service Account Authentication - Persistent, shareable credentials

• Batch Operations - 50-70% faster than sequential operations

• Advanced Formatting - Colors, fonts, borders, conditional formatting, cell merging

• Chart Creation - LINE, BAR, COLUMN, PIE, SCATTER, AREA, COMBO charts

• Type-Safe - Full TypeScript with Zod schema validation

• 100% Documented - Comprehensive guides for developers and AI agents

📦 Quick Start

Installation

# Clone repository
git clone https://github.com/oregpt/Agenticledger_MCP_SheetsOnly.git
cd Agenticledger_MCP_SheetsOnly

# Install dependencies
npm install

# Build
npm run build

Authentication Setup

1. Create Google Cloud Project (see GOOGLE_CLOUD_SETUP.md)

2. Enable Google Sheets API

3. Create Service Account and download JSON key

4. Configure environment:

# Create .env file
cp .env.example .env

# Edit .env with your credentials
GOOGLE_PROJECT_ID=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
TEST_SPREADSHEET_ID=your-test-spreadsheet-id

5. Share spreadsheets with service account email (from JSON key)

Run Tests

npm run test:integration

🛠️ Available Tools (26)

• sheets_check_access - Verify spreadsheet access

• sheets_get_values - Read cell values from range

• sheets_batch_get_values - Read multiple ranges at once

• sheets_get_metadata - Get spreadsheet metadata

• sheets_update_values - Update cell values

• sheets_batch_update_values - Update multiple ranges

• sheets_append_values - Append rows to table

• sheets_clear_values - Clear cell contents

• sheets_insert_rows - Insert rows at position

• sheets_insert_sheet - Create new sheet

• sheets_delete_sheet - Delete sheet

• sheets_duplicate_sheet - Duplicate sheet

• sheets_copy_to - Copy sheet to another spreadsheet

• sheets_update_sheet_properties - Update sheet properties

• sheets_batch_delete_sheets - Delete multiple sheets

• sheets_format_cells - Apply cell formatting

• sheets_batch_format_cells - Format multiple ranges

• sheets_update_borders - Add/modify borders

• sheets_merge_cells - Merge cells

• sheets_unmerge_cells - Unmerge cells

• sheets_add_conditional_formatting - Add conditional rules

• sheets_create_chart - Create chart

• sheets_update_chart - Update existing chart

• sheets_delete_chart - Delete chart

• sheets_insert_link - Insert hyperlink

• sheets_insert_date - Insert formatted date/time

📖 Documentation

For Developers

• README_AGENTICLEDGER.md - Complete integration guide

• PLATFORM_INTEGRATION_REPORT.md - Detailed tool documentation with real API tests

• GOOGLE_CLOUD_SETUP.md - Step-by-step authentication setup

For AI Agents

• ABILITIES_LIMITATIONS.md - Smart workarounds, best practices, optimization strategies

Example Files

• .env.example - Environment configuration template

• service-account-key.example.json - Credentials format example

• test-integration.ts - Integration test suite

💡 Example Usage

Read Data

const result = await sheets_get_values({
  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  range: "Sheet1!A1:C10"
});

Write Data

await sheets_update_values({
  spreadsheetId: "1BxiMVs0XRA...",
  range: "Sheet1!A1",
  values: [
    ["Name", "Age", "Email"],
    ["Alice", "25", "alice@example.com"]
  ]
});

Format Cells

await sheets_format_cells({
  spreadsheetId: "1BxiMVs0XRA...",
  range: "Sheet1!A1:C1",
  backgroundColor: "#4285F4",
  foregroundColor: "#FFFFFF",
  bold: true
});

Create Chart

await sheets_create_chart({
  spreadsheetId: "1BxiMVs0XRA...",
  sheetId: 0,
  chartType: "COLUMN",
  sourceRange: "Sheet1!A1:B10",
  position: { anchorCell: "E1" }
});

🔐 Security

• Never commit credentials (service-account-key.json, .env)

• Share spreadsheets explicitly with service account email

• Use environment variables for sensitive data

• Rotate keys regularly (every 90 days recommended)

• Monitor API usage in Google Cloud Console

📊 Performance

• Average Response Time: 477ms per operation

• Batch Operations: 50-70% faster than sequential

• API Quotas: 100 requests per 100 seconds per user

• Recommendation: Use batch operations for 2+ ranges

🤝 Contributing

This is an AgenticLedger platform-customized version of freema/mcp-gsheets.

AgenticLedger Customizations:

• Platform-specific documentation

• Integration test suite

• AI agent guides

• Example files and templates

📜 License

MIT License - See LICENSE file

🔗 Links

• Repository: https://github.com/oregpt/Agenticledger_MCP_SheetsOnly

• Upstream Source: https://github.com/freema/mcp-gsheets

• AgenticLedger Platform: [Platform Documentation]

• Google Sheets API: https://developers.google.com/sheets/api

📞 Support

1. Check Documentation:

   • README_AGENTICLEDGER.md - Integration guide

   • PLATFORM_INTEGRATION_REPORT.md - Tool reference

   • GOOGLE_CLOUD_SETUP.md - Authentication help

2. Run Diagnostics:

   npm run test:integration

3. Review Examples:

   • See test-integration.ts for real API usage examples

Status: ✅ Production Ready Version: 1.5.2 Last Updated: 2025-11-03 Total Tools: 26 Platform: AgenticLedger