mcp-sheet-filler

MCP server for storing and safely auto-filling tabular data. Provides tools for an AI agent to read objects, identify empty auto-fill fields, collect values, and write them back — without overwriting existing data.

tools list

demo sheet

Installation

npm install
npm run build

Related MCP server: Structured-sh

Configuration

Environment Variables

Google Sheets:

Google Sheets Setup

1. Create a Google Cloud project and enable the Google Sheets API

2. Create a service account and download the JSON key

3. Share your Google Sheet with the service account email (with Editor access)

4. Set GOOGLE_SERVICE_ACCOUNT_KEY to the JSON content or file path

Sheet structure:

• fields sheet: columns name, description, auto, instructions, type, example

• data sheet: first row is headers (field names), first column is the object key, each subsequent row is an object

Usage

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "sheet-filler": {
      "command": "node",
      "args": ["/path/to/mcp-sheet-filler/dist/index.js"],
      "env": {
        "GOOGLE_SHEET_ID": "your-google-sheet-id",
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

Development

npm run dev    # Run with tsx
npm run build  # Build TypeScript
npm start      # Run built version
npm test       # Run tests

Data Model

Fields

Schema for object fields, stored in fields table/sheet:

Objects

Data objects stored in data table/sheet. Each row is an object, each column is a field. Objects are identified by their key field (OBJECT_KEY_FIELD, default: name).

Supported Types

• string (default)

• number

• date (ISO-8601: YYYY-MM-DD)

• datetime (ISO-8601)

• url

• email

• json

• enum:val1|val2|val3

Empty Value Rules

A value is considered empty if it is: null, undefined, empty string, or whitespace-only.

Values like 0, false, "0" are not empty.

MCP Tools

filler_init

Initialize the current spreadsheet by creating data and fields tabs with header rows. Errors if either tab already exists. No parameters required.

{}

Returns { success, fieldsTab, dataTab, keyField }.

filler_list_fields

List all fields or a subset.

{ "names": ["field1", "field2"], "include_instructions": true }

filler_add_fields

Add new fields (batch).

{
  "fields": [
    {
      "name": "website",
      "description": "Company website",
      "auto": true,
      "type": "url",
      "instructions": "Find the official website"
    }
  ]
}

Returns { results: { [name]: { created: true } | { error: "..." } } }.

filler_get_objects_by_name

Get objects by their names (batch).

{ "names": ["Acme Corp", "Globex"] }

Returns { objects: [{ found, object?, missing? } | { found: false, name }] }.

filler_add_objects_by_name

Create new objects (batch).

{ "names": ["Acme Corp", "Globex"] }

Returns { results: { [name]: { created: true } | { error: "..." } } }.

filler_save_objects_no_overwrite

Save field values for multiple objects without overwriting non-empty fields.

{
  "objects": [
    {
      "name": "Acme Corp",
      "values": {
        "website": "https://acme.com",
        "founded": "1990"
      }
    }
  ]
}

Returns status for each field per object:

• saved — value was saved

• skipped_already_set — field already has a value

• rejected_unknown_field — field not in schema

• rejected_invalid_type — value failed type validation

filler_get_next_missing_fields_objects

Get objects that have missing auto-fill fields (default limit 1).

{ "limit": 1, "include_field_meta": true, "skip_filled_fields": false }

• skip_filled_fields — when true, omits already-filled field values from object.values (returns {}), reducing response size for wide sheets

Returns { found, objects, count, remain } — use this to process objects one by one or in batches.

Workflow Example

1. Agent calls filler_list_fields to understand the schema

2. Agent calls filler_get_next_missing_fields_objects to get objects with missing fields

3. Agent collects values using instructions from field metadata

4. Agent calls filler_save_objects_no_overwrite to save values safely

Error Codes

Tested with

• ChatGPT app (developer mode)

• Claude connector (custom connector)

• Cursor

• Antigravity

• VSCode

• ClaudeClaw

• telegram-functions-bot

License

ISC