wirk-mcp
Officialwirk-mcp exposes WIRK coordination and ticketing over MCP through five tools.
wirk_status: read-only start-of-session status—who you work for, your wirk, what waits, recent changes, and optional task-relevant items.wirk_query: read-only fetch by ID/short ID/exact title, list/filter items, search byaboutwords or meaning, look up receipts, sort/paginate, and wait briefly for inbox messages.wirk_write: atomically create/edit/archive/restore items, manage links and reservations, send/acknowledge messages, attach uploads or local files, and apply or propose context changes with revision expectations and request IDs.wirk_review: accept, reject, or defer proposals at the revision read, when your role permits review.wirk_show: create a live read-only page for a person from the status preset or custom view blocks, returning a link that expires after 24 hours; also revoke it.All tools support workspace selection and text/JSON output where applicable.
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., "@wirk-mcp check my wirk status and list open items assigned to me"
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.
wirk-mcp
wirk-mcp gives agents WIRK over MCP: five tools, wirk_status, wirk_query, wirk_write, wirk_review and wirk_show, whose arguments are WIRK's request bodies and whose answers are WIRK's compact text. Coordination and ticketing built for agents and the people they work with: your wirk, its context and its evidence in one wirkspace.
Install
One command installs the wirk command and this server, sets up Claude Code and Codex when they are present, and logs in:
curl -fsSL https://wirk.life/install | shBy hand, install the CLI and MCP server as separate tools from PyPI:
uv tool install wirk
uv tool install wirk-mcpInstalling wirk-mcp alone provides the server binary, not the wirk CLI command. Run wirk login, then point your agent host at the installed binary. First check claude mcp get wirk, codex mcp get wirk or grok mcp list: a server named wirk with another command is an earlier install. Replace it (Claude Code needs claude mcp remove --scope user wirk first; Codex's and Grok's adds replace it), or skip the add when it already runs this binary:
claude mcp add --scope user wirk -- "$(command -v wirk-mcp)" # Claude Code
codex mcp add wirk -- "$(command -v wirk-mcp)" # Codex
grok mcp add wirk -- "$(command -v wirk-mcp)" # GrokPackage releases are also listed on GitHub.
Both stay current by themselves: at most once an hour, after a wirk command or from its message listener, wirk installs PyPI's latest release of itself and of the wirk-mcp beside it, in place (wirk 0.4.28). A server that is already running keeps the version it started with until the host starts it again. Running the installer again also upgrades.
The server uses the configuration wirk login made (~/.config/wirk, or $WIRK_CONFIG_DIR) and only the agents' token in it; it never reads a person's own token. A new login needs no restart. In an agent chat it uses that chat's own token instead, the one wirk login in the chat made: the chat is recognised by the thread ID a Codex request carries (or CODEX_THREAD_ID) and by CLAUDE_CODE_SESSION_ID (Claude Code, in the terminal and the desktop app) or GROK_SESSION_ID (Grok) in the server's environment, never by a tool argument. That environment is fixed when the host starts the server, so one server process holds one session's identity: after /new or /resume inside one Grok terminal session, its tools may act as the earlier session. Until the chat has run wirk login, its calls answer actor_setup_required. With several wirkspaces, wirk wirkspace NAME in the chat chooses the one it works in, and the chat's calls use it without a workspace_id.
Related MCP server: 7dayrag
Use
For catch-ups about status, priorities or blockers, use wirk_status for breadth. Batch a few visible work and decision leads in the first wirk_query, then follow selected links or truncated details in the next before naming specific blockers, owners or next work. Cards and counts are leads; stop when evidence suffices and name gaps. Catch-ups are read-only and answered from WIRK: read the repository or other sources only to implement or when asked to verify, and otherwise offer to check. Old handoffs and age do not establish release or worker state. Direct MCP is preferred; the CLI also works.
An agent starts with wirk_status, optionally with a one-line task. wirk_query fetches by ID, short ID or exact title, lists with fields, finds what matters for the words in about, or looks up a receipt. wirk_write changes items and links in one batch, stating in expect the revision it read (rN on a card); completing wirk gives its evidence as reason. Context changes apply when the agent may make them; otherwise they are refused with requires_review and the agent proposes them. wirk_review accepts, rejects or defers proposals when the agent's role may review; a background agent only proposes. wirk_show returns a link to a live, read-only page for a person; anyone with the link can open it until it expires after 24 hours. wirk_status and wirk_query are annotated read-only. In wirk_write, uploads (on item.create and message.send) and attach_uploads (on item.edit) take upload IDs or absolute local file paths: the server stores each file first and sends the write only when every file is stored; set your own request_id when attaching files. format: "json" returns data instead of text. request_id may be left out: the server makes one and names it, and resending the identical body with it applies once.
What leaves the machine
The requests the agent makes and their content; the token, only as the bearer header to the configured address; and with wirk_status, the host's name and version, a session number for this server process, and the repository (host/owner/name, or a hash) and branch of the directory it runs in. No telemetry.
Changes
wirk-mcp releases in step with wirk. Since 0.4.2, a version with no line here changed nothing in the server; the matching wirk release explains it.
0.4.33: the server's instructions carry the method card and say which
Method ·lines are WIRK's own. There is no 0.4.32.0.4.31: the
wirk_writetext describes a record'sowneronitem.createanditem.edit.0.4.29: the tool text says how to reserve work, how to post on a board, that
ownertakesme, and thattextis a case-insensitive substring.0.4.28: this README describes the file paths
wirk_writetakes, the read-only annotations and releasing in lockstep. Clients update themselves from this version on.0.4.25: catch-ups are answered from WIRK alone.
0.4.17: a chat's calls use that chat's own token.
wirk_statusandwirk_queryare annotated read-only. There are no releases 0.4.18 to 0.4.22 of the server.0.4.16:
wirk_writetakes absolute file paths as well as upload IDs; the server stores each file before it writes.0.4.15:
wirk_writenames theworks_atlink.0.4.14: the
wirk_querytext carries the sort values and the fetch example.0.4.9:
wirk_queryfetches by the API's object form.0.4.8:
wirk_querytakeswait(0 to 60 seconds) withinbox=me, to hold an inbox answer for a message instead of polling.0.4.7: catch-up claims rest on checked evidence.
0.4.6: the server's instructions and the
wirk_queryandwirk_writetext are rewritten: a catch-up starts withwirk_status, batches the leads in one query and follows links before it names blockers. No tool, argument or default changed.0.4.5: messages are marked seen only for what you acted on; your inbox is the boards of the items you hold. Hosted views are described as available.
0.4.3: messages: the inbox, the board query and the
message.sendandmessage.acknowledgeoperations ofwirk_write.0.4.2: the kind
record;aboutranks by meaning on Pro and by words otherwise;max_bytesis described; agents claim work before they start it; whoever's role may review decides proposals.
Development
The tests need the wirk package installed beside this one: uv pip install -e ../wirk-cli && uv pip install -e . && python -m pytest tests -q.
Releasing
A release is a version bump merged to main with Release: publish wirk-mcp <version> in its squash body; the version must equal the wirk== pin in pyproject.toml. After the release check passes on that exact commit, the tag v<version> is created there; pushing main publishes nothing, and a tag is never moved. The tag's Release workflow waits up to ten minutes for the wirk release of the same version, tests against that public CLI wheel, attaches the wheel, the sdist and SHA256SUMS to a GitHub Release, and publishes to PyPI through trusted publishing; no token is stored anywhere.
Release wirk first: a tag whose matching wirk release does not exist fails and stays unpublished, and the next version is released in step instead of moving the tag. New GitHub releases stay prereleases until their downloaded public bytes match the build and a clean public installation passes. Retry failed jobs to reuse the successful build artifacts: identical existing assets are retained, missing assets are uploaded, and differing bytes or a moved tag stop the run. The Release workflow's manual verification input checks an existing public tag without publishing. Installed clients pick up a published release themselves, on the first wirk command an hour or more after their last check; a running server keeps its version until the host starts it again.
License
Apache-2.0. See LICENSE.
Available Tools
5 toolswirk_queryCRead-onlyIdempotent
Fetch by ID, short ID or exact title; list with fields; find what matters for about (by meaning on Pro); or look up a receipt. A result "label: query …" maps bare refs to fetch, known keys to arguments, other KEY=VALUE to fields (comma values as lists, except text, linked and folder).
Inputs: sort, wait, about, depth, +8 more.
wirk_reviewAIdempotent
Accept, reject or defer proposals at the revision you read. Anyone whose role may review decides; other roles get not_authorized. A background agent never decides.
Inputs: decisions (required), format, request_id, workspace_id.
wirk_showCIdempotent
A live read-only page for a person, from the preset status or a view config; returns its link. Anyone with the link can open it until it expires after 24 hours.
Inputs: title, blocks, format, preset, +2 more.
wirk_statusBRead-onlyIdempotent
Start here: who you work for, your wirk, what waits, and recent changes. Writes nothing.
Inputs: task, format, max_bytes, workspace_id.
wirk_writeBIdempotent
Change items and links atomically. In expect put each changed or linked-from item’s rN and the parent work of a contributes_to link; missing revisions get basis_changed. Context changes apply when you may make them; requires_review means propose with a reason.
Inputs: operations (required), mode, expect, format, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The five tools have mostly distinct roles: write mutates, query reads/searches, review decides proposals, show creates a live page, and status gives an overview. There is some potential overlap between query, show, and status because all involve reading or viewing work data, but the descriptions clarify their different outputs and side effects.
All tools share the wirk_ prefix and use short lowercase suffixes, giving a predictable namespacing pattern. The suffixes mix verbs and nouns (write, query, review, show, status), but they remain readable and consistent enough for this small set.
Five tools is well-scoped for this work-item management server, with each tool covering a distinct workflow: status, query, write, review, and show. There is no obvious bloat or thinness in the tool set.
The tool surface covers the core lifecycle: orientation, querying, atomic changes, review decisions, and sharing a live view. Minor gaps may exist around explicit deletion/archive operations or detailed assignment controls, but the main workflows appear supported.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Project tracker for AI agents and teams: file, claim, update and hand off tickets over MCP.
Patterns for designing and reviewing AI skills, agents, and multi-agent workflows. Find guidance on context economy, delegation, verification, and tool design; inspect claims, worked examples, maturity labels, and source references. Five read-only tools let agents discover relevant patterns, compare concise cards, read specific sections, and explore relationships. Hosted Streamable HTTP at https://agentic-atlas.dev/mcp/ — no installation, account, or API key required. Browse the atlas at https://agentic-atlas.dev/.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI models to perform IT service management operations on Freshservice, including managing tickets, changes, problems, releases, assets, projects, and more through a set of MCP tools.362MIT
- FlicenseNot gradedqualityDmaintenanceProvides MCP tools for hybrid knowledge base search, grounded Q&A with citations, agent execution, and ticket/account lookups.-
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to access and manage an internal support ticket queue through MCP tools, resources, and prompts, including searching and viewing tickets, adding comments, closing tickets with confirmation, reading knowledge base articles, and viewing queue summaries over OAuth-secured Streamable HTTP.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents such as Claude, Gemini, and a headless Runner to post, list, claim, report, and defer work on a single shared board through seven MCP tools. Every call carries a human-rooted chain of authority that is verified on each call, narrows at every hand-off, and can be revoked at any link.Apache 2.0