Skip to main content
Glama
workiva-mcp

workiva-mcp

by woof-xyz

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

kb_search · kb_list · kb_get · kb_add

Profiles

profile_list · profile_use

Wdata (read)

wdata_list_tables (with sql_ref) · wdata_get_table · wdata_list_queries · wdata_run_sql · wdata_run_saved_query · wdata_list_connections

Wdata (write)

wdata_create_table · wdata_upload_and_import · wdata_refresh_connection

Graph

graph_types · graph_records · graph_edits (write)

Spreadsheets

spreadsheet_list_sheets · spreadsheet_ui_url · spreadsheet_update (write)

Anything else

workiva_request (platform / wdata / chains)

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 check

Development

One-time setup after cloning — activate the pre-push gate:

git config core.hooksPath .githooks

Every 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 entries

kb/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_base

The 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 wheel

  • Local drafts overlay + kb_add

  • Workiva client foundation: credential profiles in ~/.workiva/credentials, token lifecycle, three-host transport

  • Auto-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 refresh

  • Graph + Spreadsheets tools (writes gated)

  • Escape hatch (platform / wdata / chains)

  • promote CLI: drafts → PR (workiva-kb)

  • v0.1.0 tag, uvx install verified

  • Credential profile switching: profile_list / profile_use

  • NOTICE 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 tools
graph_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

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

    A3.9/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      This 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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
    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      10
      753 npm
      MIT