Enables LLMs to read and surgically edit HTML and Markdown tables in documents while preserving original formatting and GitBook compatibility.
Also known as oborchers/tablestakes
- Stars
- 1
- Tools
- 11
- Downloads, 30 days
- 93
- Latest version
- 1.1.0
- Last commit
- Oct 25, 2026
- License
- Apache-2.0
What is tablestakes MCP?
tablestakes enables LLMs to read and surgically edit HTML and Markdown tables in documents while preserving original formatting and GitBook compatibility. It exposes 11 tools, such as update_cells, insert_row, delete_row.
Summary generated from the project's README
About tablestakes MCP server
Editing complex tables in Markdown files is difficult for AI models when they encounter collapsed HTML or messy formatting from platforms like GitBook and Notion. Tablestakes solves this by acting as a specialized interface that converts unreadable HTML tables into clean pipe format for the model to process. This allows an LLM to understand the structure and content without being overwhelmed by markup overhead.
Developers can use this server with clients like Claude Code, Cursor, Windsurf, or Claude Desktop by adding it via uvx. The server provides tools to list tables, read specific tables, and perform surgical edits such as updating cells, inserting rows, or renaming columns. It uses a version-checking system to ensure that edits are safe and do not overwrite recent changes.
What sets this apart is its ability to perform round-trip conversions. When the model writes an update, the server converts the clean pipe data back into the original HTML format, preserving specific attributes like width and inline formatting. This ensures that documents remain compatible with CMS platforms and GitBook while significantly reducing token usage during discovery and reading operations.
What you can do with it
- 1Scan large documents for tablesAn AI can quickly index a document to find all existing tables without reading the entire file content.
- 2Perform surgical cell updatesA developer can instruct an AI to change a specific value in a table row and column using minimal tokens.
- 3Maintain GitBook compatibilityUsers can edit HTML tables within Markdown files while ensuring all original HTML attributes and formatting remain intact.
Written from the project's README. Every use case is checked against a quote from it.
How to install tablestakes MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall tablestakes MCP in Claude Code
$ claude mcp add tablestakes -- uvx tablestakesInstall tablestakes MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tablestakes": {
"command": "uvx",
"args": [
"tablestakes"
]
}
}
}Install tablestakes MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tablestakes": {
"type": "stdio",
"command": "uvx",
"args": [
"tablestakes"
]
}
}
}Install tablestakes MCP in VS Code CLI
$ code --add-mcp '{"name":"tablestakes","type":"stdio","command":"uvx","args":["tablestakes"]}'Install tablestakes MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"tablestakes": {
"command": "uvx",
"args": [
"tablestakes"
]
}
}
}Install tablestakes MCP in Codex
$ codex mcp add tablestakes -- uvx tablestakesInstall tablestakes MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tablestakes] command = "uvx" args = ["tablestakes"]
Install tablestakes MCP in Gemini CLI
$ gemini mcp add -s user tablestakes uvx -- tablestakesInstall tablestakes MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tablestakes": {
"command": "uvx",
"args": [
"tablestakes"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for tablestakes 1.1.0 in an isolated container with no network and no keys. It answered and listed 11 tools.
tablestakes MCP tools 11
Read from the server with tools/listupdate_cellsBatch-update cells. Requires version hash from read_table. Each update is {row, column, value} where: - row: 0-based data row index (header row is NOT counted) - column: letter ("A"), name ("Priority"), or composite ("B:Priority") - value: new cell content (Markdown inline formatting supported) On success returns ONLY `v:{new_hash}`. On error returns JSON: {"error": "STALE_READ"|"EDIT_ERROR"|..., "message": "..."}. If STALE_READ: call read_table again for current version, then retry.
insert_rowInsert a new row. Requires version hash from read_table. Provide values as a dict mapping column identifiers to cell content. Column identifiers: letter ("A"), name ("Priority"), or composite ("B:Priority"). Omitted columns default to empty string. On success returns ONLY `v:{new_hash}`. On error returns JSON with "error" and "message" fields.
delete_rowDelete a row. Requires version hash from read_table. On success returns ONLY `v:{new_hash}`. On error returns JSON with "error" and "message" fields.
replace_tableReplace an entire table with new content. Requires version from read_table. Provide new_content as a pipe table string (header row + delimiter + data rows). The server writes back in the ORIGINAL file format: pipe stays pipe, GitBook HTML stays GitBook HTML (attributes preserved). On success returns ONLY `v:{new_hash}`. On error returns JSON with "error" and "message" fields.
create_tableCreate a new table in a Markdown file. Provide content as a pipe table. The table is written in the specified format: "html" (default, collapsed single-line HTML suitable for GitBook) or "pipe" (GFM pipe table). No version hash needed — this creates, not edits. On success returns `v:{hash}` of the new table. Use this hash with read_table and write tools to edit the table immediately. On error returns JSON with "error" and "message" fields.
insert_columnInsert a new column. Requires version hash from read_table. All existing rows are populated with default_value (empty string if omitted). On success returns ONLY `v:{new_hash}`. On error returns JSON with "error" and "message" fields.
delete_columnDelete a column. Requires version hash from read_table. On success returns ONLY `v:{new_hash}`. On error returns JSON with "error" and "message" fields.
rename_columnRename a column header. Row data is unchanged. Requires version from read_table. On success returns ONLY `v:{new_hash}`. On error returns JSON with "error" and "message" fields.
list_tablesList all tables in a Markdown file with column descriptors and row previews. Prefer this over grep for discovering table structure — returns column names, row counts, formats, and version hashes. Use search_tables to find specific data across tables.
read_tableRead a full table as a clean pipe table with version hash. Prefer this over reading files directly — handles HTML tables, preserves inline formatting, and returns the version hash needed for any edit. First line of output is metadata: v:{hash} {format} {rows}r {cols}c [{section}] Extract the 12-char hex hash after "v:" (e.g. "a1b2c3d4e5f6") and pass it as the version argument to any write tool. If a write returns STALE_READ, call read_table again for a fresh version.
search_tablesSearch for rows matching a value across one or all tables in a file. Returns matching rows with table index, row index, and version hash so you can immediately follow up with a write tool. Prefer this over grep for table data — it understands column structure and handles HTML tables. Two search modes (regex overrides pattern if both given): - pattern: case-insensitive substring match (simple, no escaping needed) - regex: full regex via re.search (e.g. ``D 1\.\d+`` for sub-items) If neither pattern nor regex is provided, returns all rows.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableoborchers/tablestakes is public and reachablegithub.com/oborchers/tablestakes ↗Pass
- Package names this repository as its sourcetablestakes names oborchers/tablestakes as sourcepypi.org/project/tablestakes/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for tablestakespypi.org/project/tablestakes/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-25github.com/oborchers/tablestakes ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from tablestakesPass
- No critical advisory in the package or its dependencies67 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtablestakes
An MCP server that gives LLMs clean, surgical access to tables trapped in messy HTML.
The Problem
Tools like GitBook, Notion exports, and CMS platforms collapse tables into single-line HTML when syncing to Markdown files. The result looks like this in your editor:
<table><thead><tr><th width="520.11">Requirement</th><th width="122.07">Priority</th><th>Priority 1-2-3</th></tr></thead><tbody><tr><td><strong>1.1</strong> Agent sees only their Salesforce-assigned cases <strong>in the currently selected organization</strong> (case is "assigned" when SF <code>Case.OwnerId</code> matches the agent's linked SF user ID)...</td><td>Must</td><td>1</td></tr></tbody></table>
This is unreadable for humans and unreliable for LLMs. Models struggle to parse collapsed HTML tables, frequently hallucinate cell boundaries, and cannot edit them without corrupting the structure.
tablestakes fixes this. It sits between the LLM and the file, converting tables to clean pipe format on read and writing back in the original format on save — preserving GitBook compatibility, HTML attributes, and inline formatting.
What the LLM Sees
Discovery — scan a 26-table document in one call:
26 tables
T0 pipe 5r 3c v:485f65f7b470 [Cross-Domain Dependencies]
A:Integration | B:Source | C:Requirements
T2 gitbook 18r 3c v:77a9495fd328 [Case List]
A:Requirement | B:Priority | C:Priority 1-2-3
T7 gitbook 3r 4c v:d9a9a45a370f [Attachments]
A:Requirement | B:Priority | C:Dependency | D:Priority 1-2-3
Read — collapsed HTML becomes a clean pipe table:
v:d9a9a45a370f gitbook 3r 4c [Attachments]
A:Requirement | B:Priority | C:Dependency | D:Priority 1-2-3
| Requirement | Priority | Dependency | Priority 1-2-3 |
| --- | --- | --- | --- |
| **5.1** View inbound attachments in-app... | Must | — | 1 |
| **5.2** Send outbound attachments... | Must | Blocked on SF API | 1 |
| **5.3** Attachment file size limits... | Should | — | |
Write — surgical cell edit, version-checked:
v:5749c94ffb1f
14 characters. The file is updated, GitBook HTML format preserved, width attributes intact.
Token Efficiency
Baseline: Claude Code's built-in Read + Edit tools operating on the same file. Measured on a synthetic 18-row, 4-column table with realistic requirement-style content (bold IDs, inline emphasis, mixed-length cells).
| Operation | Read + Edit | tablestakes | Savings |
|---|---|---|---|
list_tables (26 HTML tables) |
~28,400 tokens | ~2,500 tokens | 91% |
read_table (18-row HTML) |
~1,100 tokens | ~690 tokens | 39% |
read_table (18-row GFM) |
~780 tokens | ~690 tokens | 11% |
| Cell edit (18-row HTML) | ~35 tokens | ~27 tokens | 23% |
| Cell edit (18-row GFM) | ~99 tokens | ~27 tokens | 73% |
| 10-edit workflow (HTML) | ~1,470 tokens | ~960 tokens | 35% |
Where the savings come from:
-
Read (HTML): collapsed HTML tags (
<td>,<tr>,<th>,<strong>,width="...") are pure overhead. Pipe tables carry the same information without markup. The Read tool also addscat -nline-number prefixes. -
Read (GFM): modest savings from stripping line-number prefixes and surrounding document context. The table content itself is already clean.
-
Write: the Edit tool requires
old_string(enough context to be unique in the file) +new_string(the modified version), both generated as output tokens. For GFM,old_stringis the entire row line (~190 chars). tablestakes needs only{"row": 0, "column": "B", "value": "Should"}(~18 tokens). -
Discovery: without tablestakes, the LLM reads the entire file to find tables.
list_tablesreturns a compact index — metadata + 1 preview row per table. -
Compact pipe tables with no column padding. Per the ImprovingAgents benchmark, GFM pipe tables achieve the best token-to-accuracy ratio: 1.24x CSV cost at 51.9% QA accuracy, beating JSON (2.08x, 52.3%) and YAML (1.88x, 54.7%).
Tokenizer: tiktoken cl100k_base (GPT-4). Claude uses a different tokenizer, but relative comparisons hold. The benchmark script (script.py) constructs tables programmatically and generates tablestakes output using the actual converter code — no hardcoded strings.
Read baseline: simulate_read_tool() wraps file content in cat -n format (line-number prefix per line), matching what Claude Code's Read tool returns. The full file (document text + table) enters the LLM context.
Write baseline: for each cell edit, the script computes the minimum unique old_string by expanding leftward from the target <td> until the substring is unique in the file. new_string is the same context with the cell value replaced. This is a best-case scenario for the Edit tool — a human might include more context than the minimum.
list_tables baseline: 26 copies of an 18-row GitBook HTML table in a markdown document. Naive = Read the full file (~28k tokens). tablestakes = list_tables output with preview_rows=0..3:
preview_rows |
Tokens | Savings |
|---|---|---|
| 0 (metadata only) | ~1,230 | 96% |
| 1 (default) | ~2,530 | 91% |
| 2 | ~3,510 | 88% |
| 3 | ~4,420 | 84% |
Reproduce: uv run --with tiktoken python scripts/script.py
Quick Start
Claude Code:
claude mcp add tablestakes -- uvx tablestakes
Codex CLI:
codex mcp add tablestakes -- uvx tablestakes
Gemini CLI:
gemini mcp add tablestakes -- uvx tablestakes
Or install from PyPI directly: pip install tablestakes
Add the following JSON to your client's MCP config file:
{
"mcpServers": {
"tablestakes": {
"command": "uvx",
"args": ["tablestakes"]
}
}
}
| Client | Config file |
|---|---|
| Cursor | .cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Claude Desktop | claude_desktop_config.json |
Tools
Discovery & Read
| Tool | Purpose |
|---|---|
list_tables(file_path, preview_rows=1) |
Scan file, return all tables with metadata + preview |
read_table(file_path, table_index) |
Full table normalized to pipe format + version hash |
Cell, Row & Column Operations
| Tool | Purpose |
|---|---|
update_cells(file_path, table_index, version, updates) |
Batch {row, column, value} patches |
insert_row(file_path, table_index, version, position, values) |
Insert row at position (-1 to append) |
delete_row(file_path, table_index, version, row_index) |
Remove row by index |
insert_column(file_path, table_index, version, name, ...) |
Insert column with default value |
delete_column(file_path, table_index, version, column) |
Remove column |
rename_column(file_path, table_index, version, old_name, new_name) |
Rename header |
replace_table(file_path, table_index, version, new_content) |
Full table replacement from pipe input |
create_table(file_path, content, position, format) |
Create new table from pipe input (default: HTML) |
All write tools require a version hash from read_table — optimistic concurrency that prevents stale overwrites without locks.
Supported Table Formats
| Format | Read | Write | Round-trip |
|---|---|---|---|
| GFM pipe tables | Pass-through | In-place edit | Lossless |
| GitBook collapsed HTML | HTML → pipe | Pipe → collapsed HTML | Preserves width, data-*, inline formatting |
| General HTML tables | HTML → pipe or pretty HTML | Reconstructs HTML | Preserves structure |
While GitBook is the primary motivation, tablestakes works with any Markdown document containing HTML tables — CMS exports, Notion dumps, wiki migrations, or hand-written HTML in .md files.
Column Addressing
Columns can be referenced by:
- Letter:
"A","B","AA"(bijective base-26, like Excel) - Name:
"Priority"(must be unique) - Composite:
"B:Priority"(for disambiguation) - Index:
"0","1"(0-based)
Development
make init # First-time setup: venv + deps + pre-commit hooks
make check # All checks: format + lint + typecheck + test
make test # Run tests only
make test-cov # Tests with coverage report
Author
Built by Dr. Oliver Borchers, Executive AI and Automation Partner and Head of AI Engineering at IU Group.
License
Apache-2.0
mcp-name: io.github.oborchers/tablestakes
tablestakes MCP questions
How do I add tablestakes MCP to Claude Code?
Run claude mcp add tablestakes -- uvx tablestakes in your terminal. Add --scope user to make it available in every project.
How do I add tablestakes MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does tablestakes MCP provide?
It exposes 11 tools, including update_cells, insert_row, delete_row, replace_table, create_table.
What problem does tablestakes solve?
It solves the issue of LLMs struggling to parse or edit collapsed HTML tables found in GitBook, Notion, or CMS exports, which are often unreadable and prone to corruption.
Does it preserve HTML attributes when editing?
Yes, it preserves GitBook compatibility, HTML attributes like width, and inline formatting when writing back to the file.
How does it prevent overwriting recent changes?
It uses optimistic concurrency via a version hash required for all write tools to prevent stale overwrites.