API & Integrations

GeoSheet provides a public REST API and an MCP server for integrating with external tools and AI assistants.

Public REST API

The REST API allows you to read and write GeoSheet data programmatically.

Requirements

Professional plan or higher
An API key (created in Organization Settings > API Keys)

Authentication

All API requests require a Bearer token:

Authorization: Bearer gs_live_abc123...

Base URL

https://geosheet.app/v1

Rate Limits

Plan	Limit
Professional	100 requests/minute
Enterprise	1,000 requests/minute

Endpoints

GeoSheets

Method	Endpoint	Description
`GET`	`/v1/geosheets`	List all GeoSheets
`GET`	`/v1/geosheets/:id`	Get GeoSheet info
`GET`	`/v1/geosheets/:id/sheets`	List sheets
`GET`	`/v1/geosheets/:id/charts`	List charts

Cells

Method	Endpoint	Description
`GET`	`/v1/geosheets/:id/cells`	Read cells (query params: `sheet`, `range`)
`PUT`	`/v1/geosheets/:id/cells`	Write cells

API Key Management

Go to Organization Settings > API Keys
Click Create API Key
Name the key and select scopes:
- geosheets:read — list and read GeoSheet metadata
- geosheets:write — create and modify GeoSheets
- cells:read — read cell values
- cells:write — write cell values
Copy the key immediately — it's only shown once
Keys can be revoked at any time

Response Format

All responses use a consistent wrapper:

{
  "data": { ... }
}

Paginated responses include metadata:

{
  "data": [...],
  "meta": { "total": 100, "page": 1, "pageSize": 50 }
}

Errors return:

{
  "error": "Description of what went wrong",
  "details": { ... }
}

MCP Server

GeoSheet provides an MCP (Model Context Protocol) server so AI clients like Claude Desktop, Cursor, and other MCP-compatible tools can interact with your spreadsheets.

Hosted MCP (Recommended)

No installation needed. Configure your MCP client with:

{
  "mcpServers": {
    "geosheet": {
      "url": "https://geosheet.app/mcp",
      "headers": {
        "Authorization": "Bearer gs_live_..."
      }
    }
  }
}

Uses Streamable HTTP transport. Requires a Professional plan API key.

Local MCP (Offline)

For offline use, install the local MCP server:

{
  "mcpServers": {
    "geosheet": {
      "command": "npx",
      "args": ["@gridsheet/mcp"],
      "env": {
        "GRIDSHEET_API_KEY": "gs_live_..."
      }
    }
  }
}

Uses stdio transport. Connects to the public REST API.

Available MCP Tools

Tool	Description
`list_geosheets`	List all accessible GeoSheets
`get_geosheet_info`	Get metadata for a GeoSheet
`list_sheets`	List sheets within a GeoSheet
`get_cells`	Read cell values from a range
`set_cells`	Write values to cells
`search_cells`	Search for values across sheets

Use Cases

Claude Desktop: Ask Claude to read your GeoSheet data, analyze it, and write results back
Cursor/IDE: Reference spreadsheet data while coding
Custom AI agents: Build agents that interact with GeoSheet data
Automation: Use MCP-compatible tools to automate spreadsheet workflows

Webhooks (Coming Soon)

Webhook support for real-time notifications on spreadsheet events is planned for a future release.