mcp-sheets-form-filler

# Smart Google Sheets Template Filler (MCP Server) A Model Context Protocol (MCP) server that allows AI agents (like Claude, Antigravity, or Cursor) to intelligently fill out complex Google Sheets templates, forms, and briefs. ## 💡 Why this server? Most existing Google Sheets MCP servers treat spreadsheets as standard databases (appending new rows to the bottom). However, many real-world use cases (like marketing briefs, invoices, or application forms) require updating specific, scattered cells (e.g., date in `B3`, platform in `B6`, notes in `B10`). This server uses the Google Sheets `batchUpdate` API with `USER_ENTERED` parsing, allowing the LLM to take unstructured chat text, map it to specific cell coordinates, and update the entire template in a single API call. ## 🚀 Features - **Scattered Cell Updates:** Update `Sheet1!B3`, `Sheet1!C10`, and `Data!A1` simultaneously. - **Smart Parsing:** Supports native Google Sheets formatting (automatically recognizes dates, links, and numbers). - **Batch Processing:** Sends all updates in a single API request, avoiding rate limits. - **Secure:** Uses Service Account authentication via local credentials. ## 🛠 Setup Instructions ### 1. Google Cloud Configuration 1. Go to [Google Cloud Console](https://console.cloud.google.com/) and enable the **Google Sheets API**. 2. Create a **Service Account** in the Credentials section. 3. Generate and download a new **JSON key** for this service account. 4. Rename the downloaded file to `credentials.json` and place it in the root directory of this project. 5. **Crucial Step:** Open your target Google Spreadsheet, click "Share", and grant **Editor** access to the Service Account's email address. ### 2. Installation Clone the repository and install dependencies: ```bash git clone https://github.com/your-username/mcp-smart-sheets-template.git cd mcp-smart-sheets-template npm install ``` ### 3. Environment Variables Create a `.env` file in the root directory and add your Spreadsheet ID and the path to your credentials: ```env SPREADSHEET_ID=your_spreadsheet_id_from_the_url CREDENTIALS_PATH=/absolute/path/to/your/credentials.json ``` ### 4. Build Compile the TypeScript code: ```bash npx tsc ``` ## 🔌 Connecting to MCP Clients (Claude Desktop / Antigravity) Add the server to your MCP client's configuration file. Make sure to use the absolute path to the compiled `index.js` file. ```json { "mcpServers": { "sheets-template-filler": { "command": "node", "args": [ "/absolute/path/to/mcp-smart-sheets-template/index.js" ] } } } ``` ## 🗣️ Usage Example Once connected, you can simply drop unstructured text into your AI agent's chat: > "Here is the info for the brief: The publication date is May 25th, format is TikTok Video, and the target audience is students. Please fill out the brief spreadsheet." The LLM will automatically parse the text, generate the correct cell coordinates (e.g., `'Brief Template'!B3`), and update the spreadsheet instantly. ## 📄 License MIT License