Spreadsheet DB

What Spreadsheet DB MCP server does

Hikoutei provides a typed entity layer over local SQLite and can publish committed changes to Google Sheets asynchronously. Applications define entities with scalar properties such as strings, numbers, booleans, and primary keys, then use a request-local manager to create, update, query, and remove records.

The Spreadsheet DB MCP server uses SQLite as the application authority. Google Sheets is a secondary view for inspection, operational work, and lightweight collaboration. Normal application reads and writes stay local, so they do not wait for network calls to Sheets. The library also checks for unexpected column changes and duplicate headers, and it avoids silently replacing newer spreadsheet edits during conflicts.

How it works

A configured database file stores the entity data locally. Changes are committed to SQLite first, then placed into an asynchronous synchronization flow that projects them to Google Sheets. The documented flow includes an outbox, delivery handling, retries, deduplication, and conflict processing.

Edits made by people in the spreadsheet are brought back through polling. Accepted changes enter SQLite; conflicting changes are recorded instead of being silently overwritten. This arrangement keeps the application path independent from Sheets availability while retaining a human-readable operational view.

The design is intended for typed TypeScript applications. It sits above lower-level packages such as google-spreadsheet and @googleapis/sheets, rather than replacing their full spreadsheet APIs.

Setup and configuration

Install the package with its documented MikroORM dependencies:

npm install hikoutei @mikro-orm/core @mikro-orm/sql

Creating the local store does not require Google Cloud configuration. Initialize a database with createTypedSheets, provide a SQLite file path, and register entity definitions. Use a forked entity manager for request-local operations, then persist changes and call flush().

To enable Sheets projection, install the gcloud CLI and run npx hikoutei setup. The interactive command creates a Cloud project, service account, key, and spreadsheet, then writes environment configuration. Synchronization is enabled when HIKOUTEI_SYNC_SPREADSHEET_URL is present; without it, the setup remains local-only. The repository also points to separate guidance for credential pools, quotas, and manual configuration.

Tools and capabilities

The Spreadsheet DB MCP server’s documented capabilities include:

• Defining typed entities and scalar properties.
• Creating, finding, updating, and removing records through a local entity manager.
• Persisting transactions to SQLite with immediate local commits.
• Projecting committed changes to Google Sheets asynchronously.
• Polling Sheet edits and handling accepted changes or conflicts.
• Detecting duplicate headers and unexpected column changes.
• Retrying and deduplicating synchronization work.

Limitations and notes

The Spreadsheet DB MCP server is not a raw Google Sheets wrapper, a replacement for PostgreSQL, or an authoritative spreadsheet database. Direct row and cell manipulation is limited compared with the underlying Google Sheets clients, and full Sheets API access remains the provider’s responsibility.

The supplied material describes a TypeScript library and does not specify an MCP transport, named MCP tools, or compatibility requirements for clients such as Cursor or Claude Desktop. Those details should be verified before treating the project as a conventional MCP server integration.