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
- Create Google Cloud Project (see GOOGLE_CLOUD_SETUP.md)
- Enable Google Sheets API
- Create Service Account and download JSON key
- 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
- Share spreadsheets with service account email (from JSON key)
Run Tests
npm run test:integration
🛠️ Available Tools (26)
Reading Data (4 tools)
sheets_check_access- Verify spreadsheet accesssheets_get_values- Read cell values from rangesheets_batch_get_values- Read multiple ranges at oncesheets_get_metadata- Get spreadsheet metadata
Writing Data (5 tools)
sheets_update_values- Update cell valuessheets_batch_update_values- Update multiple rangessheets_append_values- Append rows to tablesheets_clear_values- Clear cell contentssheets_insert_rows- Insert rows at position
Sheet Management (6 tools)
sheets_insert_sheet- Create new sheetsheets_delete_sheet- Delete sheetsheets_duplicate_sheet- Duplicate sheetsheets_copy_to- Copy sheet to another spreadsheetsheets_update_sheet_properties- Update sheet propertiessheets_batch_delete_sheets- Delete multiple sheets
Formatting (6 tools)
sheets_format_cells- Apply cell formattingsheets_batch_format_cells- Format multiple rangessheets_update_borders- Add/modify borderssheets_merge_cells- Merge cellssheets_unmerge_cells- Unmerge cellssheets_add_conditional_formatting- Add conditional rules
Charts (3 tools)
sheets_create_chart- Create chartsheets_update_chart- Update existing chartsheets_delete_chart- Delete chart
Additional (2 tools)
sheets_insert_link- Insert hyperlinksheets_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 templateservice-account-key.example.json- Credentials format exampletest-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
-
Check Documentation:
- README_AGENTICLEDGER.md - Integration guide
- PLATFORM_INTEGRATION_REPORT.md - Tool reference
- GOOGLE_CLOUD_SETUP.md - Authentication help
-
Run Diagnostics:
npm run test:integration -
Review Examples:
- See
test-integration.tsfor real API usage examples
- See
Status: ✅ Production Ready Version: 1.5.2 Last Updated: 2025-11-03 Total Tools: 26 Platform: AgenticLedger