opendesk-mcp

A Model Context Protocol server for openDesk, the sovereign workplace suite that ZenDiS builds for German public administration on behalf of the Federal Ministry of the Interior.

It gives an MCP-capable assistant read-only access to the files, projects, knowledge pages, calendar, contacts, mail and chat of one openDesk instance.

Why this exists

openDesk publishes no MCP server, and there is no unified openDesk API to write one against. openDesk is a curated bundle of separate open-source products behind a shared Keycloak, and the architecture documentation lists one API per component rather than one for the suite.

That leaves every openDesk deployment, roughly 100,000 administrative workstations at the time of writing, without a way to point an assistant at its own content. This server closes that gap by talking to each bundled product directly.

The default hosts are openDesk's own deployment defaults, from helmfile/environments/default/global.yaml.gotmpl, where every service gets its own subdomain. Each one is overridable.

Calendar, contacts and mail are Open-Xchange, not Nextcloud. Nextcloud in openDesk serves files. Pointing a calendar tool at the Nextcloud host would read a different calendar, usually an empty one, and look like a data problem rather than a configuration one.

Related MCP server: AuroraDocs MCP Server

Scope and safety

Every tool in this server is read-only. There is no code path that creates, updates or deletes anything in openDesk, that sends a message or an email, and none that writes to disk or contacts a host other than the configured modules.

Each module authenticates as one account and therefore sees exactly what that account sees. openDesk's own permissions remain the access boundary; this server does not widen them.

Modules are independent. If your XWiki allows single sign-on only and rejects the password, the Knowledge tools are simply not registered and everything else keeps working. The server prints which modules it started with on stderr.

Responses are size-capped before they reach the assistant. A response body is read up to a limit and then aborted, long text is truncated with an explicit [truncated] marker, and a file above the read limit returns metadata with a note instead of its contents.

Known limitations of openDesk itself

Two of these modules depend on things that are not this server's to fix. Read this before filing a bug.

Calendar and contacts may fail on your deployment. openDesk issue #155, "openxchange CalDav & CardDav do not work", has been open since February 2025, is assigned upstream to Open-Xchange and sits in the backlog. It reports a broken ingress rewrite plus an unresolved "No session created" authentication failure on /servlet/dav. On an affected deployment these two modules cannot authenticate no matter which credentials you supply. The error message from this server says so rather than leaving you to suspect your password.

Check before configuring them:

curl -u 'username:password' 'https://dav.example.org/servlet/dav/'

Mail needs IMAP to be exposed at all. IMAP is not HTTP, so it cannot travel through the cluster's HTTP ingress that serves every other module. Whether Dovecot is reachable from outside is a decision your operator makes, which is why OPENDESK_MAIL_HOST has no default and must be set by hand.

Requirements

• Node.js 20 or newer

• An openDesk instance reachable from the machine running the server

• Credentials for at least one module

Obtaining the credentials

Files, a Nextcloud app password

1. Open the Files app in openDesk.

2. Go to Settings, then Security.

3. Under "Devices & sessions", enter a name and choose "Create new app password".

4. Copy the generated password. It is shown once.

Projects, an OpenProject API key

1. Open the Projects app in openDesk.

2. Open your avatar menu and choose "My account".

3. Go to "Access tokens".

4. Under "API", choose "Generate" and copy the key.

Knowledge, calendar, contacts and mail: the account password

XWiki, the Open-Xchange DAV endpoints and IMAP have no app-password concept of their own, so these modules use the account's credentials. Whether that works depends on how your deployment configured single sign-on. Test each one with curl (see above) before wiring it up.

Chat, a Matrix access token

1. Open the Chat app (Element) in openDesk.

2. Go to Settings, then Help & About.

3. Expand "Advanced" and copy the access token.

A Matrix access token is as powerful as the account. Treat it like a password.

Installation

git clone https://github.com/Nraitschew/opendesk-mcp.git
cd opendesk-mcp
npm install
npm run build

The build writes an executable entry point to dist/index.js.

Configuration

The server is configured through environment variables. Only OPENDESK_DOMAIN and the credentials of the modules you want are required.

Domain

Every module URL is derived from it, and every one can be overridden.

Files, Nextcloud

Projects, OpenProject

Knowledge, XWiki

Calendar and contacts, Open-Xchange

One credential enables both, because in openDesk they are the same product on the same host.

Mail, IMAP

Chat, Matrix

Limits

Half a credential is an error rather than a silently disabled module: setting OPENDESK_FILES_USERNAME without OPENDESK_FILES_APP_PASSWORD makes the server exit with a message naming the missing variable.

Connecting a client

Claude Desktop

Edit the MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opendesk": {
      "command": "node",
      "args": ["/absolute/path/to/opendesk-mcp/dist/index.js"],
      "env": {
        "OPENDESK_DOMAIN": "example.org",
        "OPENDESK_FILES_USERNAME": "first.last",
        "OPENDESK_FILES_APP_PASSWORD": "your-app-password",
        "OPENDESK_PROJECTS_API_KEY": "your-api-key",
        "OPENDESK_WIKI_USERNAME": "first.last",
        "OPENDESK_WIKI_PASSWORD": "your-password",
        "OPENDESK_DAV_USERNAME": "first.last",
        "OPENDESK_DAV_PASSWORD": "your-password",
        "OPENDESK_MAIL_HOST": "mail.example.org",
        "OPENDESK_MAIL_USERNAME": "first.last",
        "OPENDESK_MAIL_PASSWORD": "your-password",
        "OPENDESK_CHAT_TOKEN": "your-matrix-token"
      }
    }
  }
}

Restart Claude Desktop afterwards. Leave out the variables of any module you do not want.

Claude Code

claude mcp add opendesk \
  --env OPENDESK_DOMAIN=example.org \
  --env OPENDESK_PROJECTS_API_KEY=your-api-key \
  -- node /absolute/path/to/opendesk-mcp/dist/index.js

Any other MCP client

The server speaks MCP over stdio. Start it with node dist/index.js and the environment set; any client that can spawn a stdio server will work.

Tools

Only the tools of the configured modules are registered.

Files

Projects

Knowledge

Calendar

Contacts

Mail

Chat

Tool results are JSON. OpenProject's HAL envelopes are flattened, so a work package carries status, assignee and project as plain names.

Notes on the data

Recurring appointments are not expanded. A CalDAV time-range query returns the recurring master object, and this server reports the appointment as it is stored, with a recurring flag, rather than computing occurrences. Expanding recurrence correctly is a calendar engine's worth of edge cases.

Times without a zone stay without one. An iCalendar value qualified with a TZID is returned as a local wall-clock time rather than being converted, since resolving the zone needs the VTIMEZONE component. Treating such a value as UTC would shift half the appointments in the country by an hour.

Mail UIDs are per mailbox. A uid from mail_search is only valid in the mailbox it came from, and it changes when a message moves. Pass the mailbox along with the uid to mail_read.

Wiki page references

XWiki addresses a page as Space.PageName, and a nested space as A.B.PageName. Two details are easy to get wrong, and this server handles both:

• A literal dot inside a name is escaped as \.. Splitting on every dot would break exactly the pages whose names contain one, such as release notes or dates.

• A reference may be fully qualified as wiki:Space.Page. The wiki part is a separate REST path segment, not a dot-separated one.

A bare page name with no space is rejected rather than guessed at. Always pass a reference that wiki_search or wiki_list_pages returned.

Errors

A failing tool call returns a result marked as an error whose text starts with a stable machine code and names the module, so a rejected OpenProject key does not read as a broken Nextcloud:

Testing against your instance

npx @modelcontextprotocol/inspector node dist/index.js

The MCP Inspector lists the tools and lets you call them by hand, which is the fastest way to confirm the domain and credentials are right. The server also prints the configured modules to stderr on startup.

Development

npm install
npm run typecheck
npm test
npm run build

The unit tests cover configuration and URL derivation, the WebDAV multistatus parser and search-body escaping, the OpenProject filter grammar, the XWiki reference grammar, the iCalendar and vCard parsers, and the IMAP search criteria. They make no network requests, so they run anywhere.

Limitations

• Read-only by design.

• Video conferencing (Jitsi, NeoDateFix), collaborative documents (Collabora), CryptPad, Notes and the Nubus portal are not covered.

• File contents are read for text files only. Office documents and PDFs return metadata.

• Attachments are listed but never downloaded, in files, wiki pages and mail alike.

• Searches page once with the requested limit rather than paging through a large result set.

• Every tool call opens its own IMAP connection. That costs a connection setup per call, and buys not having to keep a session alive between questions.

Related

If you run only one of the bundled products rather than a whole openDesk instance, the standalone servers are a better fit:

• openproject-mcp

• xwiki-mcp

For Nextcloud on its own, the community already has several servers, including cbcoutinho/nextcloud-mcp-server.

Contributing

Issues and pull requests are welcome, particularly:

• Reports from real openDesk deployments about which modules accept password authentication, and whether CalDAV and CardDAV work on yours.

• Corrections to the API assumptions documented in the source comments.

License

Apache License 2.0. See LICENSE.

This project is independent. It is not affiliated with or endorsed by ZenDiS GmbH, the German Federal Ministry of the Interior, Nextcloud GmbH, OpenProject GmbH, Open-Xchange, XWiki SAS or Element. "openDesk", "Nextcloud", "OpenProject", "Open-Xchange", "XWiki", "Element" and "Matrix" are trademarks of their respective owners and are used here only to describe what this software connects to.