Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@opensheet show me rows from campaigns where rating is 5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your tables are plain .jsonl files on disk. Edit one cell — git diff shows one line.
Close OpenSheet, and jq, DuckDB, Excel, pandas and your AI agents can still read everything.
Spreadsheet-database tools have to put your rows somewhere. The usual answers are a database you also have to run, a storage engine that ships with the app, or a single binary file in the app's own format. All three work. All three mean the tool sits between you and your data.
OpenSheet's source of truth is a text file you already know how to read. One folder is a library,
each .jsonl inside it is a table, one line is a record. There is no database, no account, no server,
no sync. Delete OpenSheet and your data doesn't move an inch.
$ cat my-library/campaigns.jsonl
{"id":"KS-001","project":"Modular Mechanical Keyboard","raised_usd":412870,"rating":5}
{"id":"KS-002","project":"Solar Camp Lantern","raised_usd":88250,"rating":4}
$ jq -r 'select(.rating == 5) | .project' my-library/campaigns.jsonl
Modular Mechanical KeyboardThat's the whole storage format. The spreadsheet UI is a view onto it, not a wrapper around it.
Related MCP server: Universal JSON Agent MCP
Requires Python 3.9+. No pip install, no Docker, no build step.
git clone https://github.com/newgepard/opensheet
cd opensheet
PYTHONPATH=src python3 -m opensheet ~/my-library/It opens http://127.0.0.1:<free port> in your browser. Point it at a folder of .jsonl files, at a
single .jsonl file, or at an empty folder to start from scratch.
macOS desktop app — an 860 KB native shell (Swift + WKWebView, uses the system WebKit):
bash shell/build.sh
open shell/build/OpenSheet.appThis is what everything else is built around, and it is tested rather than asserted.
1. Untouched rows are written back byte-for-byte. Edit one cell in a 10,000-row table and
git diff shows exactly one changed line. Rows you didn't touch are never re-serialized — not
reordered, not reformatted, not re-escaped.
2. Non-ASCII text is never escaped. {"名前":"甲"} stays exactly that. It never turns into
{"\u540d\u524d":"\u7532"}, which is what json.dumps does by default and what makes a file
unreadable in every tool that isn't a JSON parser.
3. Sparse files stay sparse. If a row doesn't have a key, OpenSheet will not invent one for it. Adding a field to a table with 50,000 existing rows rewrites zero of them.
Undo is built as inverse commands, not snapshot rollback, specifically so promise 1 survives it:
edit a cell, press ⌘Z, save — git diff is empty. A snapshot-restore implementation would look
correct on screen while quietly re-serializing every row it touched.
Backing this up: a fingerprint check refuses to overwrite changes made behind OpenSheet's back,
writes go through a temp file plus os.replace(), and every save keeps a .bak alongside an
open-time snapshot.
Your data is a file you own — plain .jsonl, readable by jq, DuckDB, pandas, Excel and git
Undo everything — ⌘Z / ⇧⌘Z; a batch delete collapses into a single undo step
13 field types — text, number, select, multi-select, date, checkbox, URL, attachment, formula, cross-table lookup, created/updated time, auto-number. Numbers render as progress bars, currency, ratings or percentages without changing the stored value
4 view types — grid, kanban, gallery, plus per-view filters, sorts, grouping, statistics, row height, frozen columns and column order
10,000 rows stay smooth — virtual scrolling; measured at 57 ms to load and 59 ms to save a 7.5 MB table
Import and export — in from CSV, XLSX, JSON, SQLite and .grist; out to CSV, XLSX, JSON,
JSONL, Markdown and Parquet
Attachments stay local — files land in <library>/assets/, the cell holds a relative path,
nothing is uploaded anywhere
Adding an AI button to a spreadsheet is a feature. Choosing a storage format an agent can read and
write without an adapter is an architecture. OpenSheet did the second one, and everything else
follows from it: the file is line-oriented so appends are >>, the format is text so grep works,
and the writer is single so byte fidelity survives concurrent access.
An MCP server runs in the same process as the HTTP server, sharing one Store instance:
{
"mcpServers": {
"opensheet": {
"command": "python3",
"args": ["-m", "opensheet", "/path/to/libraries", "--mcp", "--mcp-root", "/path/to/libraries"],
"env": { "PYTHONPATH": "/path/to/opensheet/src" }
}
}
}Tools: list_libraries, list_tables, get_schema, query, upsert_rows.
upsert_rows returns a receipt — inserted / updated / unchanged counts plus the primary keys
for each — and supports dry_run. Rows identical to what's already on disk count as unchanged,
and the file is not touched.
Same process is not an implementation detail. Byte fidelity depends on in-process state: which bytes each row arrived as. Two processes each holding their own copy would each conclude the other's writes were "changes" and re-serialize the whole file on the next save. A second process detects the lock file and forwards to the first, so there is always exactly one writer.
Agents can also skip OpenSheet and append to the file directly. The rules that keep fidelity intact when they do are documented in the direct-write guide.
graph TD
A["my-library/"] --> B["campaigns.jsonl<br/>source of truth"]
A --> C["suppliers.jsonl"]
A --> D[".opensheet/<br/>schema · views · links"]
B --> E["store.py<br/>row passthrough · atomic write"]
C --> E
E --> F["single process"]
F --> G["HTTP + browser UI"]
F --> H["MCP over stdio"]
G --> I["native macOS shell"].opensheet/ holds field types, column widths, view definitions and cross-table links. Delete it and
you lose formatting, not data — field types fall back to inference.
The backend is Python standard library only. The frontend is plain JavaScript — no framework, no build step. The macOS shell is 184 KB of Swift on the system WebKit, not a bundled browser.
DuckDB is optional and read-only, serving the SQL panel and Parquet export. It never participates
in filtering, sorting or grouping, and it never writes. Every write goes through store.py.
No telemetry, no update checks, no CDN assets, no online demo. The browser only requests same-origin
/api/* paths, the server binds to the IPv4 loopback only, and the desktop shell holds zero TCP
connections of its own. tests/test_offline.py enforces all of this.
bash tests/opensheet-全量验收-20260815.sh329 tests: 188 JavaScript unit, 83 Python, 42 browser end-to-end (Playwright), 8 fidelity round-trip, 8 library round-trip. The fidelity tests compare files byte-for-byte rather than field-by-field — a test that only checked values would pass while promise 1 was silently broken.
Browser tests need npm install inside web/ for Playwright's Chromium.
Comments, permissions, real-time collaboration, automations, a hosted version, an online demo. Each of them needs an account system or a public address, which contradicts the first design constraint: data never leaves your machine.
This is a deliberate boundary, not a roadmap gap.
Working and used daily, with two rough edges worth knowing before you try it:
The UI is currently Chinese-only. The code, comments and interface strings are all in Chinese. English localisation hasn't been done yet.
macOS only for the desktop shell. The web version runs anywhere Python does.
Issues and PRs welcome. Two things to know before touching the storage layer:
The row-passthrough logic in store.py is the product. Changing it means keeping the fidelity
tests green, and those compare bytes, not fields.
Code comments are currently in Chinese. Translation help is very welcome.
MIT — see LICENSE.
读取表字段 schema
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| library | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The verb '读取' indicates a read-only, non-mutating operation, which is useful since siblings include upsert_rows. However, with no annotations, the description carries the full burden and does not disclose return format, permissions, or potential errors, so transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler, and the core action is front-loaded. It is concise, though slightly under-specified, which is more a completeness issue than a structure problem.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 0% parameter description coverage, the definition leaves the agent without enough context about how to supply library/table values or what the returned schema will look like. Sibling names hint at a workflow, but the description itself does not establish it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%: the input schema only gives parameter names and types. The description mentions '表字段' (table fields) but leaves 'library' unexplained, and provides no value formats or how to obtain valid inputs, so it does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '读取表字段 schema' clearly states a read operation on a table's field schema, with a specific resource and scope. It is distinguishable from siblings like query (data retrieval) and list_tables (table enumeration), though it does not name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool instead of list_tables or query, and no exclusions or prerequisite steps are mentioned. The intended workflow (first list libraries/tables, then fetch schema) is only inferable from sibling names, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出根目录内的 OpenSheet 库
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It clearly indicates a read-only listing operation scoped to the root directory, but it does not disclose details such as pagination, sorting, whether nested libraries are included, or what the response shape is. For a no-parameter list operation, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately communicates the action and scope. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter schema and no output schema, the description is nearly sufficient: it names the action, resource, and scope. Minor gaps include no statement about non-recursive behavior or return format, but the tool is simple enough that these are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no schema burden to compensate for. The description appropriately focuses on output scope rather than parameter details, matching the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('列出') and a specific resource ('根目录内的 OpenSheet 库'), clearly distinguishing this from siblings like list_tables, which lists tables rather than libraries. The scope 'root directory' adds useful precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but gives no guidance on when to choose it over alternatives, nor any exclusions or prerequisites. An agent must infer from sibling names and the description that this is the tool for listing libraries, not tables or schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出库里的 JSONL 表
| Name | Required | Description | Default |
|---|---|---|---|
| library | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden. The verb '列出' implies a read-only listing operation, but the description does not disclose output format, pagination, error behavior, or whether any library validation occurs. It is minimally transparent but not richly so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no redundant words. The operation and scope are front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter and no output schema, the description gives only minimal context. It does not explain what a 'JSONL 表' is exactly, what the agent should do with the returned list, or how to obtain a valid library value. The ambiguity around 'JSONL' and library selection leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The phrase '库里的' clarifies that the 'library' parameter identifies which library's tables are listed. However, it does not explain valid library identifier formats, whether values come from list_libraries, or how missing/invalid libraries are handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('列出' / list) and the resource ('JSONL 表' / tables) scoped to a library. It is easily distinguished from siblings like list_libraries, though it does not explicitly name the sibling it differs from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus siblings such as get_schema, query, or list_libraries. The description only states what it does, not when it should be chosen or what prerequisite steps (like selecting a library) are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
用只读 DuckDB SQL 查询表
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| table | Yes | ||
| library | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the critical read-only trait, which is essential for an agent to know this tool will not mutate data. It says nothing about return shape, SQL restrictions beyond read-only, error behavior, or permission requirements, so transparency is partial rather than complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. The key behavioral qualifier 'read-only' is front-loaded, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three required parameters, zero schema descriptions, and no annotations, the description is too sparse. An agent still lacks clarity about the 'library' parameter, whether results are returned in a specific format, and what SQL constructs are allowed beyond the read-only restriction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds little to parameter meaning beyond what the parameter names already imply. 'sql' and 'table' are self-explanatory, but 'library' remains ambiguous and there is no guidance on how the three parameters relate or what format the SQL should follow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action—querying tables via DuckDB SQL—and explicitly marks it as read-only, which distinguishes it from upsert_rows. It does not explicitly name sibling tools or contrast its scope with list/get_schema tools, so it is clear but not maximally differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The read-only qualifier implies this tool is for SELECT-style data retrieval and not for modifications, giving some usage direction. However, it does not explicitly state when to choose this over list_libraries, list_tables, or get_schema, leaving the routing mostly to inference from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按指定主键批量新增或更新，走与 HTTP 相同的 Store 并发保护。返回回执：inserted / updated / unchanged 计数与各自的主键值列表。dry_run=true 只算回执不落盘。
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| rows | Yes | ||
| table | Yes | ||
| dry_run | No | 只返回将发生的变更，不写文件 | |
| library | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavior disclosure, and it delivers: it mentions Store concurrency protection, the exact receipt format (inserted/updated/unchanged counts and key lists), and the no-persistence behavior of dry_run=true. It does not cover error or validation behavior, but the most decision-relevant side effects are explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences cover the core operation, concurrency protection, return receipt, and dry-run behavior. The most essential verb and scope are front-loaded with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description compensates for the missing output schema by stating the receipt shape, and it covers the operation's key nuances. It lacks row-structure details and failure semantics, which would help for a 5-parameter mutation tool, but it is sufficiently complete for a competent agent to call the tool correctly in the common case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20%, with only dry_run documented. The description adds meaning by identifying key as the primary key, rows as the batch payload, and clarifying dry_run semantics. However, it does not explain how rows should encode the key or what values library/table expect, leaving part of parameter construction to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '按指定主键批量新增或更新', a specific verb (upsert) and a clear resource (rows keyed by primary key). This immediately distinguishes it from the read-only and metadata sibling tools like query and list_tables, so an agent can tell what it does without needing more context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that the tool is for batch insert-or-update operations by primary key and even highlights the dry_run inspection mode. However, it never explicitly contrasts it with alternatives such as query for reads or states when not to use it. The usage context is clear but the tool-selection guidance is only implied, not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_schemalist_librarieslist_tablesqueryupsert_rowsScored across 5 tools
Each tool maps to a distinct action and resource level: libraries, tables, schema, query, and upsert. There is no meaningful overlap, and the descriptions reinforce the boundaries clearly.
Most tool names follow a clear verb_noun snake_case pattern: list_libraries, list_tables, get_schema, upsert_rows. The single-word 'query' is a minor deviation, but the overall naming style remains uniform and predictable.
Five tools is well-scoped for an OpenSheet data access server. Each tool covers a necessary step in the workflow without redundancy or bloat.
The set covers the core workflow well: discovering libraries, listing tables, inspecting schema, querying data, and upserting rows. The main gap is the lack of any delete or schema-mutation capability, but that may be intentionally out of scope for this server.
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Database for your AI agent. Turn its output into data, docs, skills, and apps you can actually use.
Zero-key temporary JSON database for agents: one tool call, no signup, no OAuth, no API keys.
