mcp-twake-project

Give your AI assistant secure access to Twake Project, the projects, boards and tasks of the Twake.ai Digital Workplace.

What is it?

mcp-twake-project is a Model Context Protocol (MCP) server. MCP is the open standard that lets AI assistants (Claude Desktop, Claude Code, Hermes Agent, Cursor, VS Code and many others) use external tools. This server exposes your Twake Project to the assistant as 47 tools: projects, boards, sections and tasks (keys, due dates, deadlines, priorities, assignees, labels, descriptions, comments, history, reminders), saved filters, the agenda and notifications, and actions as you: create a board or a task, plan it, move it, transfer it to another board, assign it, comment it, complete it, archive it, share a board.

Twake Project organises the work of a team into projects and boards, each task carrying a readable key (for example ATLAS-12). The server talks to the Twake Project backend API, as you, with an OIDC access token from your identity provider.

Nothing is done without your prior approval. Before every write, the server itself shows you the exact action (who acts, in which board, with which text and dates) through MCP elicitation, and acts only on your explicit OK. A refusal, a timeout or a client that cannot ask means nothing is done.

Related MCP server: PlainStaff MCP Server

Part of Twake.ai

Twake.ai is the truly open source and sovereign Digital Workplace developed by LINAGORA: Twake Mail, Twake Calendar, Twake Drive, Twake Chat, Twake Space, Twake Project and Twake Visio, with a single account, hosted in France or on your own infrastructure.

Open source MCP servers connect AI assistants to the whole workplace:

What it brings

• Know where the work stands: "What is left in the Atlas board? What did we finish this week?"

• Find: "Which tasks mention the September invoice?", "What is assigned to me?"

• Plan: "What does my week look like?" (the agenda of the next days, from due dates, deadlines and recurring tasks).

• Prepare: "Add a task 'Send the quote' to the Atlas board, due Thursday, priority high, assigned to Bob".

• Follow: read a task's description, its comments and its history before answering.

• Act for you, with your OK each time: "Move these three tasks to Done", "comment on ATLAS-12 that the client answered", "create a board for the new project".

• Sovereignty: the server runs next to your assistant and talks directly to your Twake Project.

Features

47 MCP tools

21 read-only, 26 that write and ask for your approval first (⚠️).

⚠️ = asks for your approval first (and for the deletions, destructiveHint). Read tools carry readOnlyHint. The server never deletes a board, and trash_task is recoverable with restore_task.

Highlights

• Keys, not only ids: a task is addressed by its key (ATLAS-12) or its id; a board by its id, its key prefix or its name.

• Informed approval: the prompt names the board, the task, the exact text and dates, who acts, and carries a unique reference.

• Descriptions that do not collide: writing a description takes its version, so a change made meanwhile is not overwritten silently (HTTP 409, read again).

• Clear errors: a role that does not allow the action, a board or task that does not exist (with the close names), an expired token, a version conflict: each says what to do.

• Sovereignty: the server runs next to your assistant and talks directly to your Twake Project.

Limits

• Sharing: Twake Project shares a board through its project. A personal project, or a project managed by a Twake Space, stays private: get_board_sharing, find_people_to_invite and the sharing writes answer HTTP 403 on such a board, and the error says so. Create a project in Twake Project itself to invite people.

• Sections: every section carries a category (backlog, unstarted, started, completed, canceled), which tells the board what it means.

• Transfer: moving a task to another board gives it a new number there; its previous key is kept. Assignees who are not members of the target board are dropped, and labels follow by name. preview_task_transfer says what would be dropped or created before anything moves.

• No deletion of a board: the API has no route for it; a task in the trash can be restored with restore_task but not destroyed for good from the server.

Requirements

• Node.js >= 22

• A Twake Project account, on a Twake.ai instance (for example https://projects.example.com)

• An access token accepted by that instance with the audience twake-projects, from a token command, a token file (0600) or a static token

• For writes, an MCP client that supports elicitation (Hermes Agent, Claude Code, VS Code…), or TWAKE_PROJECT_APPROVAL=client

• An MCP client: Claude Desktop, Claude Code, Hermes Agent, Cursor, VS Code, or any MCP-compatible assistant

Installation

npm install -g mcp-twake-project   # or run it on demand with npx -y mcp-twake-project
mcp-twake-project check            # tests the configuration

From source:

git clone https://github.com/linagora/mcp-twake-project.git
cd mcp-twake-project
npm ci
npm run build          # then run: node build/index.js

Configuration

Acting as you (access token)

Twake Project accepts the OIDC access tokens of your identity provider when they carry the audience twake-projects. Ask your identity provider administrator to add that audience to the OIDC client of your assistant, then give the server a command that prints a fresh access token:

TWAKE_PROJECT_TOKEN_COMMAND="my-token-broker twake-projects --json"   # prints {"access_token": "...", "expires_at": <epoch s>}
TWAKE_PROJECT_OIDC_ISSUER=https://sso.example.com/                    # to name you in the approval prompts

Everything is then done as you: tasks, comments and assignments carry your name. Every write is approved by you first (below).

Getting an access token by hand

For a test, copy the access token your identity provider issues for the twake-projects audience and store it in a file only you can read:

mkdir -p ~/.config/mcp-twake-project
umask 077; read -rsp "Token: " T; echo; printf %s "$T" > ~/.config/mcp-twake-project/token

An access token expires: prefer TWAKE_PROJECT_TOKEN_COMMAND for daily use.

Prior approval

With TWAKE_PROJECT_APPROVAL=elicit (the default), every write tool sends the client an elicitation request before it acts, for instance:

Twake Project : Create a section
En tant que : Alice MARTIN · alice.martin@example.com (your account)
Tableau : Projet (PROJ)
Section : À faire
Category : unstarted

Réf. 3f9a1c · Acceptez pour le faire maintenant, refusez pour annuler.

The server acts only on accept. On a refusal, a dismissal or a timeout (TWAKE_PROJECT_APPROVAL_TIMEOUT_MS, 10 minutes by default) it does nothing and tells the assistant not to retry. A client without elicitation support gets an error and nothing is done. Set TWAKE_PROJECT_APPROVAL=client only when your MCP client asks you to confirm every write tool itself. USER_LANGUAGE=fr writes the prompts in French.

Environment

One of the three token variables is required. mcp-twake-project check tests the configuration.

Use it with your assistant

Claude Desktop

{
  "mcpServers": {
    "twake-project": {
      "command": "npx",
      "args": ["-y", "mcp-twake-project"],
      "env": {
        "TWAKE_PROJECT_URL": "https://projects.example.com",
        "TWAKE_PROJECT_TOKEN_COMMAND": "/usr/local/bin/my-token-broker twake-projects --json",
        "TWAKE_PROJECT_OIDC_ISSUER": "https://sso.example.com/",
        "USER_TIMEZONE": "Europe/Paris"
      }
    }
  }
}

Claude Code

claude mcp add twake-project --scope user \
  -e TWAKE_PROJECT_URL=https://projects.example.com \
  -e TWAKE_PROJECT_TOKEN_COMMAND="/usr/local/bin/my-token-broker twake-projects --json" \
  -e TWAKE_PROJECT_OIDC_ISSUER=https://sso.example.com/ \
  -- npx -y mcp-twake-project

Hermes Agent

Hermes shows the approval prompts in the desktop app, the terminal or on your messaging platform, and declines them where nobody can answer (cron jobs, one-shot queries).

mcp_servers:
  twake_project:
    command: npx
    args: ["-y", "mcp-twake-project"]
    env:
      TWAKE_PROJECT_URL: https://projects.example.com
      TWAKE_PROJECT_TOKEN_COMMAND: my-token-broker twake-projects --json
      TWAKE_PROJECT_OIDC_ISSUER: https://sso.example.com/
      TWAKE_PROJECT_APPROVAL_TIMEOUT_MS: "330000"
      USER_LANGUAGE: fr
      USER_TIMEZONE: Europe/Paris
    timeout: 420            # longer than the approval wait
    elicitation:
      enabled: true
      timeout: 300

Recommended safe configuration

• Use a token that expires (a token command), not a static one; revoke it when you stop using the server.

• Keep TWAKE_PROJECT_APPROVAL=elicit: every write waits for your explicit OK, whatever the assistant decides. For a read-only assistant, also exclude the write tools in your MCP client:

  tools:
    exclude: [trash_task, delete_section, remove_reminder]

• Read each prompt: it says who acts (you), where (which board, which task), and exactly what.

• Task titles, descriptions and comments are written by other people (prompt injection): see SECURITY.md.

Usage examples

• "What is left to do in the Atlas board?"

• "What did we finish this week in the project?"

• "Add 'Send the quote to the client' to the Atlas board, due Thursday at 5 pm, priority high, assigned to Bob, and say the client waits for the pricing page."

• "Which tasks mention 'September invoice'?" then "open the one from the Finance board and summarise its history."

• "Comment ATLAS-12: the client answered, we resume on Monday."

• "What does my week look like?" then "move the preparation tasks to In progress".

• "Create a board 'Recruitment 2027' with the key prefix RECR in the HR project."

Troubleshooting

Development

npm ci
npm run typecheck        # sources and tests
npm run build
npm test                 # Vitest: units, the 47 tools against a recording fake API,
                         # and the built server over stdio against a fake API and identity provider

Live test against a real Twake Project, in a test board it restores at the end (a refused write first, then accepted ones that are undone):

TWAKE_PROJECT_URL=https://projects.example.com \
TWAKE_PROJECT_TOKEN_COMMAND="…" \
TWAKE_PROJECT_OIDC_ISSUER=https://sso.example.com/ \
LIVE_BOARD='Test board' node scripts/live.mjs

Contributing

Contributions are welcome: read CONTRIBUTING.md and our Code of Conduct. Please report vulnerabilities privately as described in SECURITY.md. Release notes are in CHANGELOG.md.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Copyright © 2026 LINAGORA

About

mcp-twake-project is developed by LINAGORA, French open source software publisher, as part of Twake.ai. For support, hosting or integration of Twake.ai and its AI connectors, contact LINAGORA at https://linagora.com.