Univer Workspace MCP Core
Use this server's tools for the connected user's remote Workspace. Read this Skill first, then the matching domain Skill. Tool schemas define arguments and results. When authentication is required, ask the user to reconnect or re-authorize this server in their MCP client. Never ask for a password.
Read a Sheet
To understand a Sheet Unit, call outline first. Zoom into a region or table by
calling outline again with at set to a ref from the map, locate values with
find, and read exact values with read and json true. Follow next until it is
absent. Do not scan a Sheet with execute or treat one read page as the whole
range. The sheet Skill's references/reading.md lists every option.
Skills and operation bindings
Load a Skill with skills_read and its name, or read
skill://univer-workspace/<name>/SKILL.md. Without arguments, skills_read lists
names and descriptions. With a name it returns top-level name, content and optional
resources. Read a reference or template with name and resource; full includes all
supplemental files.
For a truncated resource, repeat the same arguments with the returned cursor.
The shared Skills describe operations such as api show and compile-svg.
Use the table below to select the MCP tool. Worktree operations are aliases of the
corresponding pr operations. When a tool named here is not in your tool list, that
step is unavailable in this connection. Tell the user instead of guessing.
Admin tools require ?toolsets=admin or ?toolsets=all. Files tools require the files
toolset. An executor restriction can hide content tools even with all selected.
When the server instructions say the connection is an agent identity, they override
every rule here that leaves readiness, merging or the link to the user.
| Operation | MCP tool | Binding |
|---|---|---|
whoami |
whoami |
Connected identity |
repo list |
repo_list |
Owned or joined repositories |
repo view |
repo_view |
Repository details, including public repositories |
repo create |
repo_create |
Admin |
repo edit, repo rename |
repo_edit |
Admin; rename uses slug |
space browse |
space_browse |
Tree discovery |
space find |
space_find |
Name discovery |
share |
share |
Link Sharing of a Personal Space file; pass the url as unit with trunk true to read it |
space node create, space node rename, space node move, space node trash |
space_node |
Admin; action selects create, rename, move or trash |
issue list |
issue_list |
Team Space Issues |
issue view |
issue_view |
Include comments for the full discussion |
issue create |
issue_create |
Record a request |
issue edit |
issue_edit |
Update fields |
issue comment |
issue_comment |
Post Markdown body |
issue close, issue reopen |
issue_set_state |
State closed or open |
label list |
label_list |
Admin |
label create, label edit, label delete |
label_write |
Admin; action selects create, edit or delete |
search issues, search prs |
search |
Kind issues or prs |
pr list, worktree list |
pr_list |
Diagnose tasks |
pr view, worktree view |
pr_view |
Resolve Worktree id and state |
pr create, worktree create |
pr_create |
Start a task |
pr edit, worktree edit |
pr_edit |
Update task metadata |
pr ready, worktree ready |
pr_ready |
Ready only on explicit user completion/review request; undo true returns ready to draft |
pr merge, worktree merge |
pr_merge |
Admin; explicit user request only, except for an agent identity |
pr discard, worktree discard |
pr_discard |
Admin; irreversible, explicit user request only |
browse |
browse |
Generate a review URL |
unit list |
unit_list |
Staged Units in one Worktree |
unit add |
unit_add |
Stage an existing Univer Resource |
unit create |
unit_create |
Create an empty Worktree-local Unit |
execute |
execute |
Run Facade code and commit mutations |
outline |
outline |
Sheet only; unit and either trunk true or worktree; zoom with at, continue with from, limit depth and budget |
read |
read |
Sheet only; unit, scope, and range; content selects both, display, formula, style, or formula+style; max limits cells; json true returns typed values |
find |
find |
Sheet only; unit, scope, and terms; in selects values or formulas; case makes matching case-sensitive; sheets limit the search; from and max page hits |
inspect |
inspect |
Read stored content |
screenshot |
screenshot |
Render images |
import |
import |
Create from uploaded Office bytes |
export |
export |
Download Office output |
api find |
api_find |
Search API-name terms |
api show |
api_show |
Read exact signatures and examples |
skills list, skills get, skills read |
skills_read |
List, get or read one resource |
resources registries |
resources_registries |
Admin; SVG catalogs |
resources find |
resources_find |
Admin; search SVG assets |
resources export |
resources_export |
Admin; SVG text |
blob get |
blob_get |
Files; original-file metadata |
blob upload |
blob_upload |
Files; publish original bytes |
blob download |
blob_download |
Files; bytes and ETag |
blob replace |
blob_replace |
Files; conditional replacement |
asset download |
asset_download |
Files; embedded image bytes |
html-view validate |
html_view_validate |
Core; validate declarative bindings |
html-view create |
html_view_create |
Core; save a page draft |
| Read HTML View HTML and ETag | html_view_read |
Inline .univer.html source and strong ETag |
| Replace HTML View | html_view_replace |
Validate inline HTML and save a revision draft |
| Read HTML View draft status | html_view_draft_get |
HTTP-only; share the page only when published |
compile-markdown |
compile_markdown |
Files; Markdown to Modern Doc |
export-markdown |
export_markdown |
Files; selected native blocks to Markdown |
compile-svg |
compile_svg |
Files; SVG to a Slide page |
compile-typst |
compile_typst |
Files; Typst bundle to Doc |
print-pdf |
print_pdf |
Files; PDF download |
lint |
lint |
Files; layout diagnostics |
file upload create |
file_upload_create |
Reserve a byte transfer |
job get |
job_get |
Poll a long-running operation |
auth login, auth status, auth logout |
unavailable | Sign-in belongs to the MCP client; use whoami for identity |
config, daemon, screenshot setup, skills path, resources cache path, resources cache clear, -v |
unavailable | Local environment management has no remote tool |
Concepts and identities
- A Space (repository) contains a visible tree of Nodes. A Team Space is shared;
access follows membership and role. Its repository name is owner/slug. A Personal
Space is the connected user's owner/personal and contains personal files.
Repository arguments also accept a bare slug that uniquely matches
repo_list, Space IDs, or Workspace URLs. Unknown or ambiguous slugs require owner/slug; the error lists matching candidates. Older Team Spaces without slugs use their Space ID. - A Node is a position identified by nodeId. Every Node may have children, even a Resource Node. An organizational Node has resource null.
- A Resource is product content attached to a Node. A Univer Resource has kind univer and one Unit type, Sheet, Doc, Slide, Base or Board. Stage its resourceId. A Blob has kind blob, MIME, byte size and availability, with no Unit identity. Upload or download Blobs directly; never stage them into a Worktree.
- A Unit is the collaboration content identity addressed by unitId. Use it for content tools. A Worktree-local Unit is created inside a task; the server allocates unitId, resourceId and nodeId, and merge activates its destination.
- A Worktree (pull request) isolates one task from shared files until merge. A user-scoped Worktree belongs to the connected user's Personal repository and may stage editable files from Personal or Team Spaces. It is not a Personal Space. A Space-scoped Worktree belongs to one Team Space, contains only that Space's Units, and can be private or visible to the Space.
- Team Issues and pull requests share the Space's number sequence. Older Worktrees may have number null and use their id. An Issue is a discussion and request, not a Worktree; Personal Spaces have no Issues.
Never interchange spaceId, nodeId, resourceId, unitId, Worktree id or pull request
number. Take identities and confirmed revisions from tool results, never names.
Content tools take the Worktree id returned by pr_view, not its number.
space_find and space_browse take repo for a repository reference. Content creation
tools such as unit_create, import and compile tools keep space for the destination.
Use paths and names for discovery and disambiguation only. space_find and
space_browse discover files before staging; unit_list lists only staged Units.
The resources operations search an SVG catalog, not Workspace files.
Worktree rule
Start every new editable Unit task in a new Worktree. HTML View pages publish
outside Worktrees. pr_list is diagnostic,
not permission to reuse another draft because its name or Unit looks suitable.
Continue an existing Worktree only for rework of the same task, when this agent
already worked in that known Worktree or the user supplies its identity for that
rework, and its state is draft or ready. If identity is uncertain, start a new one.
Continue draft directly. Only writes need draft: reading tools such as inspect,
read-only execute, screenshot, export, export_markdown and print_pdf work
on a ready Worktree unchanged. Before the first write of an explicitly requested
rework, return ready to draft once with pr_ready and undo true. Leave the rework
in draft until a new explicit user completion or review request.
Never reuse merged or discarded Worktrees; stage the current file anew.
Manage Space Nodes
Use space_node to create organizational Nodes at the Space root or beneath a
stable parent nodeId. A Resource Node can be a parent when its capabilities allow
children. Use returned nodeId as the parent for later Unit creation.
Creation writes directly to the Space and cannot be undone by Worktree discard.
After an unknown result, browse the exact parent before deciding whether to retry.
Sibling names need not be unique; a same-name result is not proof of creation.
Rename and move use stable Node IDs. Choose either a parent or the current Space
root as the destination. The service reads back desired metadata after an
interrupted rename or move; if the result is still unknown, inspect the directory.
Trash recursively removes a subtree from its Space location. Only do it when the
user explicitly requests that action. Retain trashBatchId and nodeCount. Never
blindly repeat an unknown trash result. No restore or permanent Trash deletion
tool is available here.
Work from an Issue
- Resolve the repository with
repo_listorrepo_view. Readissue_viewwith comments enabled. The latest discussion may narrow the brief. Usesearchwith kind issues and assignee @me to find assigned work across Team Spaces. - Use the Issue references' resource.id and nodeId to identify files. If a reference is unavailable, tell the user rather than guessing a replacement.
- Start a new Space-scoped Worktree titled #N followed by the Issue title. The title ties the task to the Issue; no automatic Issue link is created.
- Verify and hand off. Post the review URL and a concise account with
issue_comment, identifying the comment as posted on the user's behalf. - Leave the Issue open and leave merging to the user unless explicitly asked or the server instructions say otherwise.
Issue creation and comments are not idempotent. After an unknown write result,
read the discussion before repeating it. Labels and assignees require triage
rights; report a permission denial. Record follow-up work with issue_create
when appropriate without expanding the requested task.
When the user wants to create, edit or import an Agent Skill, read skill-creator with skills_read first.
Start a task
For an existing file, resolve the repository, then find its Resource Node with
space_find or space_browse. Compare path, spaceId, nodeId, resourceId and Unit
type when several candidates match. Ask the user if the target remains ambiguous.
Create a new Worktree with pr_create, stage the exact resourceId with unit_add,
and confirm the returned unitId with unit_list.
For a Personal file choose a user-scoped Worktree. For a Team file choose a user-scoped Worktree for a private personal task, or that Team's Space-scoped Worktree when the task belongs to the team. Use Space visibility only when members should see the draft.
For a new page, dashboard or form backed by live Sheets, or a change to one, read the
html-view-creator Skill first and follow it. It uses html_view_create to save a
.univer.html draft outside a Worktree.
A page is not a Slide, Board or other Unit. If the connection cannot draft pages,
say so and stop; never create a substitute Unit.
Revise a page with html_view_read then html_view_replace. Edit the returned HTML
and draft with its strong ETag and a new idempotency key. On conflict, read again
and reconcile. Publishing a revision preserves the page identity and URL.
For a new Unit file, create the Worktree first. Use unit_create for an empty Unit,
compile_markdown to create a generated Modern Doc without a placeholder (read
the doc Skill), compile_typst for a Typst Doc, or import for Office content.
Choose the destination Space and stable parent nodeId deliberately. Do not add
an unrelated Unit to an existing task Worktree.
Every creating tool takes an idempotency key. Generate a new random value, such as a UUID, for each new operation. Reuse it only to retry the same call with identical arguments. Never derive it from names or reuse a key from earlier work. Where a schema requires a key, supply it. Conversion keys use 16 to 200 URL-safe letters, digits, underscores or hyphens. After an unknown content commit, read back before retrying.
Pages
html_view_create and html_view_replace only save drafts. Give the user
draft.previewUrl, say the page is not live until they publish it in Workspace,
and end your turn. Before saying whether a page is live or still a draft, sharing its link or revising it,
call html_view_draft_get with the returned draft ID. Users publish in Workspace without telling you. Share shareUrl only when
state is published. On rejected, ask what to change. On conflicted, read the
page again with html_view_read and draft again. On expired, draft again with a
new idempotency_key. MCP cannot publish or reject a draft.
Edit one Unit
Read the sheet, doc, slide, base or board Skill before Facade code.
For cross-Unit content, read the Host and Source Skills, then the embed Skill or
cross-unit-formula Skill. Charts referencing another Unit use the embed Skill.
These topics persist stable Source unitId and load Source content on demand.
Do not stage a read-only Source merely to reference it, or resolve it by name.
Use execute with the explicit Worktree and Unit. Captured mutations commit as
one revision; read-only code creates none. There is no separate save operation.
inspect is always read-only and takes either trunk true or an explicit Worktree.
Execution injects only the selected root, workbook for Sheet, doc, presentation,
base or board. Never redeclare it. Sheet execution uses the explicit Unit's
Workbook, never an active Workbook.
Use the public Facade with the original image source. Supported BASE64 images
written with execute are stored as Workspace FileIds with bytes stored separately;
later reads return that UUID. Docs created by compile_markdown, compile_typst or
import keep their images inline, so reads return BASE64 data URIs that already
contain the bytes. Browser clients load both forms automatically; no manual asset
upload or mutation storage handling is needed. When readback returns a UUID and you
need the original bytes, use asset_download with that id and Worktree.
Facade API lookup
Use api_find with API-name keywords or identifier fragments when no symbol is
known. Terms are case-insensitive and searched independently, not combined as AND
or interpreted as intent. Its optional Unit filter retains shared APIs.
Pass a found symbol directly to api_show. For a known class, type or exact
Class.member, use api_show immediately, batching known symbols. Read authoritative
signatures, documentation, referenced types and examples. Do not guess argument
shapes or enum values. Only find accepts a Unit-type filter. Follow returned
cursors when a class is truncated.
File handling
Reserve a transfer with file_upload_create for the required purpose. It returns
an upload object with upload_id, upload_url and a browser page_url. The user or
agent uploads bytes to that capability URL with PUT, or the user selects them on
the upload page. These links expire in ten minutes; ready uploads remain available
for one hour after reservation. Never pass a local file path to a tool.
import,blob_uploadandblob_replaceconsume upload_id. Choose purpose office-import for Office input or blob for original files.html_view_validateandhtml_view_createtake exactly one of inline html or html_upload_id. Reserve purpose html-view with media_type text/html for a local page, upload its bytes, then pass its upload_id as html_upload_id. HTML must be valid UTF-8 and at most 512 KiB. Reuse the upload and idempotency_key on creation retries.html_view_readreturns inline HTML and its strong ETag.html_view_replaceaccepts inline html only, with that ETag and a new idempotency_key.compile_svgtakes SVG text and optionally an assets_upload_id for a svg-assets ZIP. Use the page SVG as text and bundle its asset files in that ZIP.compile_typsttakes bundle_upload_id for a typst-bundle ZIP with typst.json at its root, orderedpages/*.typ, an optional prelude and optionalassets/. The manifest requires at least{ "schemaVersion": 1, "targetUnitId": "report", "pages": ["pages/01.typ"] }and may declaretitleandprelude. Put shared definitions in the prelude instead of#importor#include. Store PNG, JPEG, GIF, WebP or SVG images under bundle-rootassets/and reference them as#image("assets/name.png", width: 240pt, height: 120pt). targetUnitId is a local compiler ID, not a Workspace Unit: compile_typst always creates a new Doc. Never put an existing unitId there. The result returns it ascompiledTargetUnitId; use only the returnedunit.unitIdafterwards. Errors block apply; after warnings, compare ascreenshotwith the intended layout.compile_markdowntakes Markdown text and optionally assets_upload_id for a markdown-assets ZIP. Its returned sourceMap is the only way to update or export those blocks later; keep it in your notes for the task. A hand-built map is rejected. A Doc not compiled from Markdown has no map: read it withinspector read-onlyexecute.resources_exportreturns SVG text, not files. Use that text in authored content.export,print_pdf,blob_downloadandasset_downloadreturn expiring download links. They last fifteen minutes. Download the bytes before expiry. To replace an edited original file, reserve and upload its bytes, then useblob_replacewith the exact quoted ETag returned byblob_download.- Short screenshots arrive as image content when they fit the synchronous image
budget. Larger or long-running screenshot results provide download links.
export_markdownreturns Markdown, a refreshed sourceMap and asset download links. Its Markdown uses Univer directives such as::heading[...]and:span[...]{...}; convert them when the user asks for plain Markdown. print_pdfhas no paper, orientation, range or fit options. Content wider than the default page continues on the next page; tell the user rather than moving content unless they ask for that edit.
The compile tools apply when destination arguments such as worktree, space or unit are present and apply is omitted; explicit apply: false with them is rejected. Without destination arguments they compile only.
For a running job, poll job_get until succeeded or failed. Do not treat a job
handle as completed output. Successful job results carry the original tool output;
screenshot job results carry download links. After an unknown creation result,
retry only the same operation with its original upload and idempotency key.
Read the blob Skill for original files and the html-view Skill for live HTML
backed by Sheet data; html-view-creator sets the order of page work. Read the source
Sheet, then, unless the user already named a style, ask which style they want as design.md
describes, in the same message as your plan for the page. End your turn and wait for the
answer before you write, validate or publish a page. If they leave the choice to you
(你来定, 随便, 默认就行), use Night Gauge (night-gauge, 仪表夜航). Never silently choose
another style. Start from that style's complete template. Templates are English starting
points; write the page in the language and conventions of the user's conversation as design.md
describes, without i18n dictionaries or language switches. Controls write Sheet cells
or append rows; show recalculated source values, never page-side Sheet formulas, copied
data or fallback numbers. Blob publication and replacement write directly without Worktree
review; apply them only to the intended destination.
html_view_create and html_view_replace return a draft with previewUrl,
repositoryVisibility and sorted privateSourceUnitIds. Once html_view_draft_get
confirms published, return its immersive shareUrl and explain that anyone
with the link can view the page and its declared sources only when visibility is
public and the private-source list is empty; otherwise signed-in access is
required for the page and all its data. Signed-out visitors and signed-in
non-members are read-only; page writes are rejected for them. Follow the HTML View
Skill's sharing guidance: ask before using admin repo_edit to make a repository
public, which immediately publishes everything in it, and keep source Sheets in
the same public repository or list the private sources.
SVG resource catalog
When a Unit needs icons, logos, emoji or illustrations, use resources_registries,
resources_find and resources_export. Handles identify catalog assets. These
admin tools return SVG source for incorporation in the page or document.
Verify and hand off
- Read Sheet values, types, and formulas with
readand json true. Read stored content withinspector read-onlyexecutefor other Unit types or raw cell metadata. - Capture screenshots for Sheet layout, Doc pagination and every Slide page.
- Only mark the Worktree ready with
pr_readywhen the user explicitly says the work is finished or requests review. Otherwise, leave the verified changes in draft. - Read it with
pr_viewand confirm draft, or ready if explicitly requested. - Generate the edited Unit's review URL with
browse. - Return the review URL, pull request number, Worktree id and Unit id to the user.
Do not merge or discard unless explicitly requested. Discard is irreversible.
An agent identity follows the server instructions instead: it marks its verified
pull request ready, merges it with pr_merge and returns the share url.
To resume same-task rework, continue draft directly; return ready to draft with
pr_ready and undo true only before an explicitly requested write.
There is no separate close or reopen tool for a pull request.