Skip to main content

title: llm-workiq description: Use Microsoft WorkIQ tools with the LLM command-line tool.

Use Microsoft WorkIQ's Microsoft 365 tools with LLM, Simon Willison's command-line tool and Python library.

The plugin launches the official workiq mcp server, discovers its tools, and keeps one stdio connection open for the life of the toolbox. WorkIQ handles Microsoft authentication and access to your tenant. No HTTP bridge, local port, or custom token handling is required.

Prerequisites

  • Python 3.10 or later and LLM 0.36 or later.
  • The official Microsoft WorkIQ CLI installed and available as workiq on your PATH.
  • A Microsoft 365 account with the access, licensing, and tenant consent required by your WorkIQ deployment.

Sign in using WorkIQ before using this plugin:

workiq auth login

The available WorkIQ versions and authentication commands can differ by distribution. Use the official installation instructions for your tenant; check workiq --help if auth login is not available.

Installation

Install directly from this repository:

llm install git+https://github.com/stefanstranger/llm-workiq.git

Or install a local checkout:

llm install -e 'C:\github\llm-workiq'

The plugin is not yet published on PyPI.

Usage

Use a model that supports tool calling:

llm -T WorkIQ "What meetings do I have tomorrow?" --td
llm chat -T WorkIQ

Select your model as usual:

llm -m "openrouter/openrouter/free" -T WorkIQ "What is my latest discussion with my manager Jess?" --td

The selected model/provider must support tools. Availability and tool support of OpenRouter's free routing can vary.

Do not start workiq mcp in another terminal. The toolbox starts and owns its subprocess. It does not connect directly to https://workiq.svc.cloud.microsoft/mcp: the local WorkIQ CLI manages that authenticated connection.

Inspect or restrict tools

List the tools without sending a prompt to a model:

llm tools list WorkIQ

All tools advertised by your WorkIQ server are exposed by default, including write tools if your server provides them. Restrict the toolbox to selected MCP tool names when appropriate:

llm -T 'WorkIQ(tools=["ask", "fetch"])' "What meetings do I have tomorrow?" --td

Tool names shown to the model have a WorkIQ_ prefix, for example WorkIQ_fetch. The tools option takes the original, unprefixed MCP names. An unavailable tool name produces an error instead of being silently ignored.

Executable and timeout

The default executable is workiq and the timeout is 120 seconds per MCP request. Increase it for long-running agentic queries:

llm -T 'WorkIQ(timeout=300)' "Summarize this week''s project discussions" --td

On Windows, the plugin resolves npm's workiq.cmd shim. You can also specify an explicit executable, using escaped backslashes in toolbox JSON strings:

llm -T 'WorkIQ(command="C:\\Users\\you\\AppData\\Roaming\\npm\\workiq.cmd")' "List my meetings" --td

command can be an argv list, such as ["node", "C:\\path\\to\\workiq.js"]. The plugin appends mcp automatically. It does not interpret shell command strings.

Python

import llm
from llm_workiq import WorkIQ

workiq = WorkIQ(tools=["ask", "fetch"])
try:
    model = llm.get_model("your-tool-capable-model")
    response = model.chain("What meetings do I have tomorrow?", tools=[workiq])
    print(response.text())
finally:
    workiq.close()

Behavior and data handling

  • Tool discovery is cached; tool calls share the same subprocess and are serialized. Both ordinary prompts and interactive chat can reuse it.
  • The plugin supports MCP initialization, paginated tool discovery, notifications, server pings, tool calls, text/structured results, and image/audio results when the server provides them. It is not a general MCP client for resources, prompts, sampling, or elicitation.
  • A timeout or connection failure closes the subprocess. The failed operation is not automatically replayed, because a write might already have taken effect. A subsequent request can start a fresh connection.
  • WorkIQ tool errors are returned to LLM as exceptions, not successful text.
  • Subprocesses close at interpreter exit; Python callers can close them explicitly.
  • WorkIQ results are sent to the model provider you select. LLM may also record tool calls and results in its local logs. Use a provider approved for your work data, and configure LLM logging as needed.
  • The plugin adds no approval UI. Enabling write tools permits the model to request those actions; use a tool allow-list if you only need reads.

Development

uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build

Tests use a fake local MCP subprocess. They require no Microsoft account, network access, or model API key.

Publishing

The Publish to PyPI workflow runs on pushes to main, including merged pull requests, or manually through GitHub Actions with main selected. It skips versions already published on PyPI.

Configure the pypi GitHub environment with an environment secret named PYPI_API_TOKEN containing your PyPI API token. For the first release, use an account-scoped token; after the project exists, replace it with a project-scoped token. Environment approval rules can protect publishing.

For each release, update version in pyproject.toml and refresh the lockfile with uv lock before merging into main. The workflow runs tests and Ruff checks, builds the wheel and source distribution, and validates package metadata before uploading to PyPI. Published versions cannot be overwritten.

After the first successful publication, install the plugin with llm install llm-workiq.

License

Apache-2.0. This is an independent integration, not an official Microsoft product.

Metadata

Release files for llm-workiq 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llm-workiq 0.1.0
File Size Uploaded Provenance Actions
llm_workiq-0.1.0.tar.gz 44.9 kB Without provenance Details for llm_workiq-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llm-workiq 0.1.0
File Interpreter ABI Platform Actions
llm_workiq-0.1.0-py3-none-any.whl Python 3 none any Details for llm_workiq-0.1.0-py3-none-any.whl

Total release size: 55.9 kB

Release files / llm_workiq-0.1.0.tar.gz

Download URL llm_workiq-0.1.0.tar.gz
Size 44.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4c6500f743b3a92885972d14548c7ede6b34091ac2b596d084bebb6036f38c43
BLAKE2b-256 checksum
How to use checksums
07ab31e156d53e3f7aac7f005478724e0af9569a0b0cdb691598f7171df94939
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / llm_workiq-0.1.0-py3-none-any.whl

Download URL llm_workiq-0.1.0-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f10ee156532028446932eee5e88f703dc3713f24ee5c0fe18c401c938820f613
BLAKE2b-256 checksum
How to use checksums
e9a12dab4eedfe971422c18a2350d24fc29922d6232f8f545fa237a7d5d31edc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for llm-workiq 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page