operator MCP server
Commit Nov 13, 2026Connects coding agents to OpenProject to manage work packages, log time, and follow team conventions.
Also known as DanielEsc0911/operator-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is operator MCP?
operator connects coding agents to OpenProject to manage work packages, log time, and follow team conventions.
Summary generated from the project's README
About operator MCP server
Connecting coding agents to OpenProject allows developers to manage work packages and track progress without leaving their development environment. This server acts as a bridge that enables AI clients to read and update tasks, triage notifications, and log time directly. It is designed for developers using tools like Claude Code, Cursor, Windsurf, and various CLI agents who want their AI to follow specific team rules and workplace conventions.
Setup is handled via a setup wizard that requires an OpenProject URL and an API key. The server can be installed as a standalone binary on macOS and Linux or run using npx for Windows and Alpine environments. Once configured, the agent can use tools like briefing to summarize pending work, create or update work packages, and manage time entries. It also supports custom team conventions to ensure the agent follows specific naming or closing rules automatically.
What you can do with it
- 1Manage work packagesHave your agent create, update, or comment on specific tasks within OpenProject.
- 2Enforce team standardsEnsure the AI follows specific branch naming or task closing rules defined by your team.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
OPENPROJECT_CONVENTIONS_PATHOPENPROJECT_READ_ONLY
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledanielesc0911/operator-mcp is public and reachablegithub.com/danielesc0911/operator-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/danielesc0911/operator-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYour coding agent can read your whole repository and still has to ask "which ticket is this?". It can't see your OpenProject, so you paste work packages into the chat by hand, and the house rules (branch names, who closes what) get restated every session.
OPerator connects the line. Your agent reads and updates work packages, triages notifications and logs time, and it follows your workplace's written conventions while doing so.
You: what's on my plate?
Agent: 3 work packages assigned to you in Acme:
#1284 Bug In progress Fix login redirect loop
#1301 Task New Migrate invoice export
#1312 Task New Review Q3 access audit
Install
On macOS or Linux (x64 or arm64), one line. No Node.js, no sudo:
curl -fsSL https://operator.daer.dev/install.sh | sh
The script downloads one gzipped binary, checks it against the release's SHA-256,
puts it in ~/.local/bin and starts the setup wizard. To update, run the same line
again. It says what it found (Upgrading 1.2.0 → 1.3.0, or npx → 1.3.0 if you
ran OPerator through npx before), and the wizard offers to keep your connection and
moves each agent onto the binary.
| Option | Effect |
|---|---|
sh -s -- --no-setup |
Install and stop there, without the wizard |
OPERATOR_VERSION=1.3.0 |
Pin a release |
OPERATOR_INSTALL_DIR |
Install into another folder |
sh -s -- --lang es or OPERATOR_LANG=es |
Speak Spanish (the default follows your locale) |
¿En español? The installer, setup, install, doctor and --help speak
Spanish when your locale is Spanish (LANG=es_ES.UTF-8 and the like), or when you
pass --lang es. What your agent reads (tool descriptions, errors) stays in English.
Have Node.js 22 or newer? npm fetches the package on demand. This is also the way to install on Windows and Alpine:
npx operator-mcp setup
Grab it from the latest release.
The files are named operator-mcp-<linux|darwin>-<x64|arm64>.gz, and SHA256SUMS
covers each .gz. Unpack the file, make it executable and put it on your PATH.
macOS marks browser downloads as quarantined, so clear that flag once:
gunzip operator-mcp-darwin-arm64.gz
chmod +x operator-mcp-darwin-arm64
xattr -d com.apple.quarantine operator-mcp-darwin-arm64
./operator-mcp-darwin-arm64 setup
Verifying a release
Every binary, SHA256SUMS and the npm tarball carry a signed build provenance attestation, made
by the release workflow from this repository. Check a download before you run it
(needs the GitHub CLI):
gh attestation verify operator-mcp-darwin-arm64.gz --repo DanielEsc0911/operator-mcp
The same command verifies the .tgz attached to the release. install.sh is served
from operator.daer.dev, which you have to trust; it checks SHA256SUMS from the
GitHub release before it installs anything.
The wizard
operator-mcp setup takes about a minute, and the installer starts it for you. It
asks where your OpenProject lives, takes an API key, checks the line before saving
anything, and patches every agent it finds:
Where does your OpenProject live? e.g. openproject.acme.com
› openproject.acme.com
Your API key. Make one at https://openproject.acme.com/my/access_tokens
(older instances: My account → Access token). It stays on this machine.
› •••••••••••••
Line's open done Ada Lovelace (ada@example.com) · 12 projects
Which agents should OPerator patch into?
› [x] Claude Code
[x] Codex CLI
[x] Gemini CLI
[x] Cursor
Confirm
↑↓ move · Space select · Enter confirm
Patching in done Claude Code added ~/.claude.json
done Codex CLI added ~/.codex/config.toml
done Gemini CLI updated ~/.gemini/settings.json
done Cursor added ~/.cursor/mcp.json
An address without a scheme is taken as https://; plain http:// is refused
unless the host is loopback. Along the way you pick a
default project (or none) from the projects where you can create work packages:
type part of a name or identifier to search them, ↑/↓ and Enter to choose. The wizard finishes with the same checks
operator-mcp doctor runs. Then restart your agent and ask it "what's on my
plate?". Run operator-mcp doctor (or npx operator-mcp doctor) any time to check
the connection.
Works with your agents
setup registers agents at the end. Run install on its own whenever you add a new
agent or a second profile:
npx operator-mcp install # detect agents, ask which to register
npx operator-mcp install --yes # register every detected agent, no prompt
It writes only OPerator's own entry, leaves your other servers untouched, and backs
up any file it changes (one rolling .bak next to it, replaced on each run).
| Agent | Where it writes | How to check it worked |
|---|---|---|
| Claude Code | claude mcp add --scope user |
/mcp lists openproject as connected |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows); no Linux build, so not offered there |
Settings → Developer shows openproject running |
| Codex CLI | ~/.codex/config.toml |
codex mcp list shows openproject |
| Gemini CLI | ~/.gemini/settings.json |
/mcp lists openproject |
Antigravity CLI (agy) |
~/.gemini/config/mcp_config.json |
agy mcp list shows openproject |
| Qwen Code | ~/.qwen/settings.json |
qwen mcp list shows openproject |
| Kimi CLI | ~/.kimi/mcp.json (older releases) |
kimi mcp list shows openproject |
| Kimi Code | ~/.kimi-code/mcp.json |
kimi mcp list shows openproject |
| iFlow CLI | ~/.iflow/settings.json |
iflow mcp list shows openproject |
| Kiro | ~/.kiro/settings/mcp.json |
the MCP panel shows openproject |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
Settings → MCP shows openproject |
| Cursor | ~/.cursor/mcp.json |
Settings → MCP shows openproject enabled |
| opencode | ~/.config/opencode/opencode.json |
/mcp lists openproject |
| MiMo Code | ~/.config/mimocode/mimocode.json |
/mcp lists openproject |
The installed binary registers itself by its absolute path, which Claude Desktop
needs because it starts servers with a minimal PATH. With npx instead, Claude
Desktop must find Node on its own PATH; when it can't, install the binary or put
the absolute path of npx in the entry.
Registering by hand
For an agent OPerator doesn't detect, or if you'd rather write the config
yourself. Every MCP client wants the same two facts: run npx, with the arguments
-y operator-mcp@<version> — or, if you installed the binary, run its absolute path
(~/.local/bin/operator-mcp, expanded) with no arguments. The snippets below pin the
release the way install does, so an agent never silently starts a newer server than
the one you tested: replace <version> with the output of npx operator-mcp --version.
Leave the pin off (plain operator-mcp) only if you want every start to float to the
latest release.
claude mcp add openproject --scope user -- npx -y operator-mcp@<version>
Use --scope project instead to check the server into a repo for your team (it
lands in .mcp.json); --scope local limits it to the current project, just for you.
[mcp_servers.openproject]
command = "npx"
args = ["-y", "operator-mcp@<version>"]
{
"mcpServers": {
"openproject": { "command": "npx", "args": ["-y", "operator-mcp@<version>"] }
}
}
{
"mcpServers": {
"openproject": { "command": "npx", "args": ["-y", "operator-mcp"] }
}
}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"openproject": {
"type": "local",
"command": ["npx", "-y", "operator-mcp@<version>"],
"enabled": true
}
}
}
{
"mcpServers": {
"openproject": { "command": "npx", "args": ["-y", "operator-mcp@<version>"] }
}
}
This is the common MCP shape. Any client that accepts a stdio server takes it — check your client's docs for which file it reads.
{
"servers": {
"openproject": { "type": "stdio", "command": "npx", "args": ["-y", "operator-mcp@<version>"] }
}
}
Credentials never appear in these files. They live in
~/.config/operator-mcp/<profile>/config.json, written with 0600 permissions, so
your MCP config stays safe to check into a repo.
What your agent can do
| Area | Tools |
|---|---|
| Identity | whoami |
| Discovery | briefing · standup · list_projects · list_users · get_work_package · search_work_packages · my_work |
| Tasks | create_work_package · update_work_package · comment_work_package · list_activities · link_work_packages |
| Notifications | list_notifications · mark_notifications_read · watch_work_package |
| Time & metadata | log_time · list_metadata |
| Conventions | conventions · add_convention · remove_convention |
| Escape hatch | api_request |
"What's pending?", "what's new?", "what's on my plate?" all land on briefing: your open work,
unread notifications and recent changes in one call, so even a small model answers in one step.
Time entry activities depend on the work package, so list_metadata with
kind: "activities" needs a workPackageId. Lists come back as { total, ... } with one
urlTemplate for links, and default to 20 rows so a reply stays small.
The API key is yours, so the server already knows who you are: my_work and your
notification feed need no further configuration.
Conventions: teaching your agent how you work
Every profile carries a markdown manual at
~/.config/operator-mcp/<profile>/conventions.md. It is handed to the agent at the
start of every session, so your rules apply without anyone restating them:
## Git / GitLab
- Branch: `{type}/{wp-id}-{slug}` → `bug/1234-fix-login-redirect`
- Commit subject: `[#1234] <imperative summary>`
- MR title must contain `#1234` so GitLab links back to the work package.
## Workflow
- Move to `In progress` only once a branch exists.
- Never close a work package yourself — set `Developed`, QA closes it.
setup writes a starter file you can edit. Or tell an agent a rule in conversation
and it records it with add_convention, so the rule outlives the session. Rules are
only ever appended; removing one takes an explicit instruction from you, and the
file is backed up first.
Sharing with a team: point everyone at one file, check it into your repository, and the manual becomes versioned, reviewed in merge requests, and identical for everyone.
OPENPROJECT_CONVENTIONS_PATH=/path/to/repo/conventions.md
Safety: what your agent can and cannot do
The boundary is your API key's permissions: whatever that user can do in OpenProject,
an agent holding the key can attempt through api_request. OPerator narrows that:
- There is no
delete_*tool, so a vague instruction cannot delete a work package.api_requestalso refusesDELETEunless you setOPENPROJECT_ALLOW_DELETE=1in the server's environment, which an agent cannot set for itself. - These calls need
confirm: true: every non-GETapi_request,add_convention,remove_convention, andmark_notifications_readwithall: true. The tool descriptions tell the agent to set it only after you explicitly agreed, which guards against instructions planted in work package or comment text. It is a contract with the agent, not a lock. - Ordinary work package writes (
create_work_package,update_work_package,comment_work_package,link_work_packages,log_time,watch_work_package) are not confirm-gated, so an agent can make them without asking. The server tells the agent that text in work packages, comments and notifications is data, never instructions, but that is guidance, not enforcement. Use read-only mode or a limited key if you need a guarantee. - When an agent passes the
lockVersionit got fromget_work_package, a colleague's later edit makes the update fail, and for a description the agent is told to compare and ask you before retrying. Without alockVersionthe tool uses the current one, so that protection does not apply. - Read-only mode is the hard guard: it refuses every write before it leaves the machine. Use a key with limited permissions as well when the agent should not reach everything.
Two workplaces at once
Each workplace is a profile with its own credentials and its own rules:
npx operator-mcp setup --profile acme
npx operator-mcp setup --profile personal
Each registers under its own server name, openproject-acme and
openproject-personal, so both can be connected at the same time and your agent
never confuses one instance for the other.
Read-only agents
Run npx operator-mcp setup --read-only (flags also take the --flag=value form, like --profile=acme) to save the profile as read-only, or add this
to the server's entry in your MCP config (the environment overrides the profile):
{ "env": { "OPENPROJECT_READ_ONLY": "1" } }
Every create, update, comment, time entry, watch change, and convention edit is refused before a request leaves the machine. Reads work normally.
Configuration
| Variable | Effect |
|---|---|
OPENPROJECT_URL |
Instance URL. Overrides the stored profile. |
OPENPROJECT_API_KEY |
API key. Overrides the stored profile. |
OPENPROJECT_PROFILE |
Profile to load. Same as --profile. |
OPENPROJECT_DEFAULT_PROJECT |
Project used when a tool's project is omitted. |
OPENPROJECT_CONVENTIONS_PATH |
Read the manual from somewhere else. |
OPENPROJECT_READ_ONLY |
Refuse every write. Anything except empty, 0, false, no or off turns it on, so a typo stays safe. Overrides the profile. |
OPENPROJECT_ALLOW_DELETE |
Set to 1 to let api_request send DELETE. Off by default. Environment only. |
OPENPROJECT_ALLOW_INSECURE_HTTP |
Set to 1 to allow a plain http:// URL to a non-loopback host. The API key then travels unencrypted. Environment only. |
OPERATOR_LANG |
es or en for the command-line text. Same as --lang; otherwise LC_ALL, LC_MESSAGES, LANG decide. |
Environment variables win over the stored profile, which makes CI easy: set
OPENPROJECT_URL and OPENPROJECT_API_KEY and skip setup entirely.
Troubleshooting
Running setup alone is not enough on older versions: it saved credentials but
never told your agent the server existed. Run npx operator-mcp install, then
restart the agent. Almost every "it can't find my projects" report is this.
Restart the agent completely; most clients only read their MCP config at startup. Then confirm the server starts on its own:
npx -y operator-mcp
It should sit there silently waiting for JSON-RPC on stdin. Press Ctrl+C. Any error message it prints instead is the real problem.
The agent found the server but no credentials for the profile it asked for. If you
registered a --profile server, run setup --profile <name> for that same profile.
The token was revoked or mistyped. Generate a new one at My account → Access
tokens → API and re-run setup.
The instance URL is wrong, or it's behind a VPN this machine isn't on. Open the URL in a browser from the same machine to confirm.
OPerator uses Node's built-in fetch, which ignores HTTPS_PROXY unless you opt in. On
Node 24 or newer set NODE_USE_ENV_PROXY=1 in the server's env (together with
HTTPS_PROXY); older Node versions have no built-in proxy support.
The npx path requires Node 22 or newer (node --version). The installed binary
needs no Node.
Development
npm install
npm run typecheck # src and tests
npm test # mocked, never touches a real instance
npm run test:docker # live suite on a throwaway OpenProject container
npm run build
Two runtime dependencies. See AGENTS.md for the working rules.
License
MIT © Daniel Escalona
operator MCP questions
What can my coding agent do with OPerator?
Your agent can read and update work packages, triage notifications, log time, and follow your workplace's written conventions.
How do I install it on Windows or Alpine?
If you have Node.js 22 or newer, you can use npm to fetch the package with npx operator-mcp setup.
Where are my credentials stored?
Credentials are stored in ~/.config/operator-mcp/<profile>/config.json with 0600 permissions to keep your MCP config safe for version control.