workiva-mcp
This server provides MCP tools for interacting with the Workiva platform, enhanced by a self-building knowledge base (KB) that automatically surfaces fixes for failed API calls.
Knowledge Base (KB) — Search, list, get, and add entries to a growing database of API quirks and known issues. Failed requests include relevant KB entries in error messages.
Profiles — List and switch between saved Workiva credential profiles for different environments.
Wdata (Read) — List tables, get schemas, run ad‑hoc Trino SQL (with qualified table references), execute saved queries, and list connections.
Wdata (Write) (WORKIVA_ALLOW_WRITES=1 required) — Create tables, upload CSV/TSV/JSON files, import data, and refresh connections.
Graph — List available record types, fetch graph records (type filter mandatory), and apply edits (create/update/delete records and relationships).
Spreadsheets — List sheets within a spreadsheet, generate direct UI URLs, and update sheets via structured operations (edit ranges/cells, apply formats, resize columns).
Escape Hatch — workiva_request enables direct HTTP calls to any Platform, Wdata, or Chains API endpoint for unsupported operations (GET always allowed; other methods require write permissions).
Write Safety — All write tools are disabled by default to prevent accidental mutations; they must be explicitly enabled.
Draft KB Contributions — Record new quirks locally via kb_add; drafts are immediately searchable and can later be promoted to the shared KB through a formal process.
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., "@workiva-mcp list all Wdata connections"
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.
workiva-mcp
An MCP server for the Workiva platform that pairs API tools with an accumulating knowledge base of confirmed API behaviour — the quirks, dead ends, and undocumented requirements that otherwise cost every agent (and every teammate) the same hour of rediscovery.
The mechanism that makes the pairing matter: failing API calls
automatically attach the matching KB entry. An agent that hits
400 "unable to match urn" gets the fix inside the error message itself,
without ever knowing the KB exists.
Status: v0.1.0 — the full planned surface is live: 22 tools across the KB, credential profiles, Wdata, Graph and Spreadsheets, plus the escape hatch and the drafts → PR contribution loop.
Install
claude mcp add --scope user workiva -- uvx --from git+https://github.com/woof-xyz/workiva-mcp@v0.1.0 workiva-mcp--scope user registers the server once for your account, available in
every directory. Without it, claude mcp add defaults to local scope —
private to you in the one directory you ran it from, which is why the server
seems to vanish in every other project. The third option, --scope project,
writes a .mcp.json into the repo so teammates get the server on clone.
Add -e WORKIVA_ALLOW_WRITES=1 before -- to enable write tools (see
Write safety). Pin a tag — uv caches git resolutions, so an unpinned
main silently freezes at whatever commit it first resolved. Upgrading =
re-add with the new tag. Credentials go in ~/.workiva/credentials
(Credentials below); the KB tools work with no credentials at all.
Related MCP server: cocoon
Tools
Group | Tools |
KB |
|
Profiles |
|
Wdata (read) |
|
Wdata (write) |
|
Graph |
|
Spreadsheets |
|
Anything else |
|
Every API tool runs through the auto-attach mechanism: failures come back wearing the matching KB entries, resolution included.
What the KB knows
25 seeded entries, all confirmed against the live API in July 2026: 4 blockers (no API path exists — e.g. connections cannot be created programmatically), 12 gotchas (the obvious approach fails first — e.g. Wdata SQL cannot reference tables by name), and 9 nuances. Entries are dated, version-pinned, and carry the literal error strings they match.
Layout
workiva-mcp/
src/workiva_mcp/
server.py # MCP tools
kb.py # KB toolchain: parse, validate, build index, search
client.py # Workiva API client: credentials, token refresh, three hosts
promote.py # KB drafts -> branch -> PR (planned)
kb/ # the knowledge base: entries/*.md + SCHEMA.md + index.json
tests/
.githooks/ # pre-push gate: ruff + pytest + kb checkDevelopment
One-time setup after cloning — activate the pre-push gate:
git config core.hooksPath .githooksEvery push then runs ruff, the tests, and the KB check first
(git push --no-verify bypasses in an emergency).
uv run workiva-mcp # boots the stdio server
uv run pytest # tests
uv run ruff check . # lint
uv run python -m workiva_mcp.kb check # validate entries + index currency
uv run python -m workiva_mcp.kb build # rebuild kb/index.json after editing entrieskb/index.json is generated — never edit it by hand; edit kb/entries/*.md
and rebuild.
Register with Claude Code from a clone:
claude mcp add --scope user workiva -- uv run --directory <path-to-clone> workiva-mcp(--scope user makes the dev server available everywhere; drop it to keep
it confined to the directory you register it from.)
Credentials
# ~/.workiva/credentials (chmod 600)
[settings]
default_profile = sandbox
[default]
client_id = ...
client_secret = ...
[sandbox]
client_id = ...
client_secret = ...
# optional per-profile endpoint overrides:
# token_url / platform_base / wdata_base / chains_baseThe file is re-read at call time, so edits — rotating a secret, switching
default_profile — take effect on the next call without restarting the
server. With no file at all, WORKIVA_CLIENT_ID / WORKIVA_CLIENT_SECRET
serve the default profile. WORKIVA_CREDENTIALS_FILE overrides the file
location.
Switching profiles is a tool call, not a file edit: profile_list
shows every profile with the active one marked, and profile_use("sandbox")
makes all subsequent API calls authenticate as that profile — a fresh token
is fetched on the next call. The switch is session-scoped: nothing is
written to the file, and a restart returns to the configured default
(profile_use("") does the same without restarting). Precedence:
profile_use override > WORKIVA_PROFILE > [settings] default_profile >
[default].
Write safety
The server is read-only by default: tools marked WRITE (create table,
upload/import, connection refresh, …) refuse with an explanatory message and
touch nothing. Enable writes with WORKIVA_ALLOW_WRITES=1 in the server's
environment, or allow_writes = true under [settings] in
~/.workiva/credentials — the file is re-read at call time, so flipping it
takes effect immediately, and an explicit env value (even 0) always wins.
Read-only means no user-visible workspace mutations: wdata_run_sql's
internal temp-query mechanics stay allowed.
Capturing new knowledge
kb_add writes drafts to ~/.workiva/kb/drafts/ (override with
WORKIVA_KB_DRAFTS) — local, instant, no review, never part of the package.
Search reads bundled entries and your drafts, so a quirk you hit today
helps you again tomorrow, before any review happens. Drafts carry
confidence: reported and pass the same schema linter as real entries.
Promotion into the shared KB is a deliberate human act:
uv run workiva-kb list # what's waiting locally
uv run workiva-kb promote <draft-id> ... # re-stamp as confirmed, branch, commit, open PR(--no-pr for branch+commit only, --keep-drafts to leave local copies,
--confidence to override the confirmed re-stamp.) Workspace-specific
findings simply never get promoted.
Roadmap
Scaffold: package, entry point, empty stdio server
KB data vendored: 25 entries, schema, CC-BY-4.0 license
KB toolchain: parse + validate + index build + weighted search, tests, pre-push gate
KB tools:
kb_search/kb_list/kb_get, KB packaged into the wheelLocal drafts overlay +
kb_addWorkiva client foundation: credential profiles in
~/.workiva/credentials, token lifecycle, three-host transportAuto-hint mechanism + read-only Wdata tools
SQL execution, saved queries, connections listing
Write gate (
WORKIVA_ALLOW_WRITES/allow_writes) + modifying Wdata tools: create table, upload → import → poll, connection refreshGraph + Spreadsheets tools (writes gated)
Escape hatch (platform / wdata / chains)
promoteCLI: drafts → PR (workiva-kb)v0.1.0tag,uvxinstall verifiedCredential profile switching:
profile_list/profile_useNOTICE file — deferred until copyright ownership is settled (see the plan's open item); Apache-2.0 is complete without it
License
Code: Apache-2.0 (see LICENSE). KB entries under kb/, once landed:
CC-BY-4.0.
Available Tools
20 toolsgraph_editsA
WRITE. Apply graph edits: a JSON array of operations — create_record, create_relationship, set_properties, delete_relationship, delete_record. Records are created via edits; there is no POST /graph/records (KB: graph-records-created-via-edits).
WARNING: if the response carries no temp-id map, do NOT retry — the records were likely created anyway. Read back with graph_records and reconcile (KB: graph-edits-id-map-unreliable).
Inputs: operations_json (required). Returns: result
graph_recordsA
Fetch graph records of one type (find names via graph_types).
A type filter is mandatory — the API rejects an unfiltered listing (KB: graph-records-filter-required). Set expand_relationships to walk the record's edges.
Inputs: type_name (required), max_records, expand_relationships. Returns: result
graph_typesA
List all graph record type names available in this workspace.
Inputs: no named parameters. Returns: result
kb_addA
Record a newly discovered Workiva quirk so nobody researches it twice.
Add an entry whenever you lost more than a few minutes to something not obvious from the docs — especially "there is no API for this".
entry_id stable kebab-case slug, e.g. wdata-upload-requires-zip severity blocker (no API path) | gotcha (obvious approach fails) | nuance symptom pipe-separated literal error strings — the primary search key; required for blockers and gotchas tags comma-separated api_version pass the dated X-Version you ran against, if known
The draft lands in ~/.workiva/kb/drafts/ — local to this machine, searchable immediately. A human later promotes it into the shared KB by PR.
Inputs: title (required), surface (required), entry_id (required), severity (required), +6 more. Returns: result
kb_getA
Retrieve one KB entry in full, including its evidence.
Inputs: entry_id (required). Returns: result
kb_listA
List KB entries, optionally filtered by surface (wdata, platform, graph, spreadsheets, chains, auth) or severity (blocker, gotcha, nuance).
Reading all blocker entries before planning Workiva work is cheap and prevents committing to approaches that have no API path.
Inputs: surface, severity. Returns: result
kb_searchA
Search accumulated Workiva API knowledge BEFORE attempting unfamiliar work, and whenever a call fails unexpectedly.
Pass the literal error text if you have one — entries are indexed on symptom strings. Otherwise pass the task ("create incoming connection", "write to spreadsheet"). Answers: is this possible via the API at all, what is the real endpoint, what will fail first.
Inputs: query (required), limit. Returns: result
spreadsheet_list_sheetsB
List sheets in a spreadsheet, including any bound dataset.
Inputs: spreadsheet_id (required). Returns: result
spreadsheet_ui_urlA
Build the Spreadsheets UI URL for a spreadsheet or sheet.
No API returns this URL, but the query-result export endpoint and human users both need it; it is constructed from the workspace id (KB: spreadsheet-ui-url-format). Defaults to the first sheet.
Inputs: spreadsheet_id (required), sheet_id. Returns: result
spreadsheet_updateA
WRITE. Write to a sheet. operations_json is one of editRange, editCells, applyFormats or resizeColumns; all indices 0-based and inclusive.
Send numbers as JSON numbers, not strings, or CURRENCY/PERCENT formats will not apply (KB: spreadsheet-write-operations). Waits for the async operation to complete.
Inputs: sheet_id (required), spreadsheet_id (required), operations_json (required). Returns: result
wdata_create_tableA
WRITE. Create a Wdata table.
columns_json: JSON array of {"name": ..., "type": ...} column dicts — valid types are catalogued in the KB (kb_get wdata-column-types).
Inputs: name (required), columns_json (required), description. Returns: result
wdata_get_tableB
Full detail for one Wdata table, including its column schema.
Inputs: table_id (required). Returns: result
wdata_list_connectionsA
List Wdata connections (live query -> spreadsheet links).
A filter pair is REQUIRED — either (source_type, source_id) or (destination_type, destination_id), e.g. source_type "wdata_query" with a query id. Connections cannot be CREATED via the API (KB: connections-cannot-be-created-via-api) — only listed and refreshed.
Inputs: source_id, source_type, destination_id, destination_type. Returns: result
wdata_list_queriesA
List saved Wdata queries with id, name and updated timestamp.
Inputs: no named parameters. Returns: result
wdata_list_tablesA
List Wdata tables: id, name, databaseId, lastUploaded — and sql_ref, the exact qualified reference SQL requires.
Wdata SQL cannot reference tables by name (KB: wdata-sql-requires-qualified-table-refs). Copy sql_ref verbatim into your query: SELECT ... FROM <sql_ref> AS "alias". The databaseId doubles as the workspace id in Spreadsheets UI URLs.
Inputs: no named parameters. Returns: result
wdata_refresh_connectionA
WRITE. Refresh an existing connection and wait for it to settle — this updates the destination spreadsheet's data in place.
Find connection ids with wdata_list_connections. Connections can only be refreshed, never created, via the API.
Inputs: connection_id (required), timeout. Returns: result
wdata_run_saved_queryB
Execute a saved Wdata query by id (see wdata_list_queries) and return its rows.
Inputs: query_id (required), timeout, max_rows. Returns: result
wdata_run_sqlA
Execute one-off Wdata SQL and return rows.
Tables MUST be referenced by the sql_ref from wdata_list_tables — "databaseId"."tableId" AS "alias" — plain names do not resolve. The dialect is Trino. Mechanics: there is no ad-hoc SQL endpoint, so this creates a temporary saved query, runs it, downloads the CSV result, then deletes the temporary query.
Inputs: sql (required), timeout, max_rows. Returns: result
wdata_upload_and_importA
WRITE. Upload a local .csv/.tsv/.json (or .zip of one) into a Wdata table and import it: upload -> import -> poll until settled, in one call (upload alone does NOT import — KB: wdata-upload-then-import-two-steps).
Row-level import errors are surfaced if the import fails. Note the import adds system columns to the table, and re-uploading an identical filename 409s (KB: wdata-duplicate-filename-409).
Inputs: table_id (required), file_path (required), timeout, delimiter. Returns: result
workiva_requestA
Escape hatch for any endpoint not wrapped by a dedicated tool (tags, parameters, pivot views, folders, file downloads, admin, ...).
surface — which host the path is relative to (KB: three-distinct-api-hosts): platform https://api.app.wdesk.com (X-Version added for you) wdata https://h.app.wdesk.com/s/wdata/prep/api/v1 chains https://h.app.wdesk.com/s/wdata/oc/api/v1
body_json / params_json are JSON strings. GET is always allowed; any other method counts as a WRITE here and requires writes enabled (read-style POSTs like query execution have dedicated tools that stay available). If a call fails in a way no KB entry explains, that is new knowledge — record it with kb_add.
Inputs: path (required), method (required), surface (required), body_json, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a distinct operation within its domain (KB, Wdata, Graph, Spreadsheets, general request). No two tools overlap in purpose; the knowledge base tools are clearly differentiated from data operations, and the escape hatch covers anything not wrapped.
Names follow domain-specific prefixes (kb_, wdata_, graph_, spreadsheet_) with verb_noun patterns mostly, though some graph tools use plain nouns (graph_types) and the escape hatch uses workiva_request. Minor inconsistency across groups but still predictable.
20 tools is well-scoped for the Workiva API surface, covering multiple sub-APIs without being overwhelming. Each tool serves a clear purpose, and the count feels balanced.
Covers core workflows: KB management, Wdata CRUD and SQL, graph operations, spreadsheet updates, and a general escape hatch. Missing direct spreadsheet creation and some admin operations, but the escape hatch fills gaps effectively.
Maintenance
Related MCP Connectors
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
MCP server for AI access to Swagger by SmartBear.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis MCP server enables intelligent API testing automation by combining RAG knowledge retrieval with tool execution capabilities. It allows QA engineers to perform natural language-driven API testing with contextual knowledge support.-
- AlicenseNot gradedqualityBmaintenanceAn MCP server that provides a single tool for discovering, auto-installing, sandboxing, and calling any API from the printing-press corpus. It enables agents to seamlessly find and execute API operations without per-API setup.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server providing tools for read-only SQL queries, REST API calls, sandboxed Python execution, and resource lifecycle management, enabling multi-step research and data tasks.MIT
- AlicenseAqualityCmaintenanceAn MCP server that automatically discovers API endpoints from any codebase, generates and runs tests, and produces per-role QA audit reports in PDF and XLSX.10753 npmMIT