<!-- mcp-name: io.github.RyanKramer/wisegrid-mcp -->

# WiseGrid MCP

Read and write [WiseGrid](https://wisegrid.co) sheets from Claude, Cursor, or
any MCP client. List sheets, page through rows, add and update records, and run
reports — from inside a conversation.

Unlike the other servers in this family, these tools operate on **your real
data**, so an API key is required.

## Install

```json
{
  "mcpServers": {
    "wisegrid": {
      "command": "uvx",
      "args": ["wisegrid-mcp"],
      "env": {
        "WISEGRID_API_KEY": "wg_live_xxx"
      }
    }
  }
}
```

Or `pip install wisegrid-mcp`.

| Variable | Required | Purpose |
|---|---|---|
| `WISEGRID_API_KEY` | yes | Create one in WiseGrid under Settings |
| `WISEGRID_BASE_URL` | no | Override for self-hosted instances |

The key's scopes decide what these tools can reach. Grant read-only scopes if
you only want the agent to look.

## Tools

| Tool | What it does |
|---|---|
| `whoami` | The key's identity, scopes and rate limit — call this first when debugging |
| `list_sheets` | Sheets the key can see, cursor-paginated |
| `get_sheet` | Sheet + columns + first page of rows, in one call |
| `list_columns` | Column IDs, which cell dictionaries are keyed by |
| `list_rows` | Rows, cursor-paginated; each carries the `version` you need to update it |
| `add_rows` | Bulk insert, partial success, max 2000 |
| `update_row` | Update one row's changed cells, version-checked |
| `update_rows` | Bulk update, version-checked per row, max 2000 |
| `delete_row` | Delete a row and its subtree — requires `confirm=True` |
| `list_reports` / `get_report` / `run_report` | Reports and their rows |

## Things that will bite you otherwise

**Cells are keyed by column ID, not column name.** `{"101": "Acme Corp"}`, not
`{"Client": "Acme Corp"}`. Call `get_sheet` or `list_columns` first.

**Updates are version-checked.** Every row carries a `version`; you pass the one
you read, and if the row changed in the meantime you get `version_conflict`
instead of a silent overwrite. That is a normal outcome to handle — re-read the
row, decide whether your change still applies, then retry. Blindly bumping the
version to force the write is how concurrent edits disappear.

**`update_row` merges, `update_rows` overwrites.** The single-row tool takes
only the cells you changed. The bulk tool replaces the row's cell set, so send
the full set you want the row to end up with.

**`delete_row` takes the children too.** It removes the row and its entire
subtree, it is not undoable through the API, and it requires `confirm=True`
for exactly that reason. Read the rows first.

**Writes are idempotent.** Each carries an `Idempotency-Key`, so a retry after a
timeout cannot double-apply. Rate limits are honoured via `Retry-After`.

## Development

```bash
git clone https://github.com/RyanKramer/wisegrid-mcp
cd wisegrid-mcp
pip install -e .
WISEGRID_API_KEY=wg_live_xxx wisegrid-mcp
```

## About

Built by [WiseGrid](https://wisegrid.co). Full REST API reference at
[wisegrid.co/docs/api](https://wisegrid.co/docs/api).

MIT licensed.