TeamRetro MCP Server

How to use

You use this MCP server by running it as a local process or via an AI client that can load MCP configurations. The server exposes a set of tools that map to TeamRetro endpoints, enabling you to list, create, update, and delete teams, users, actions, retrospectives, health checks, and reports. Configure your AI client to connect through one or more MCP channels, supply authentication credentials, and then start issuing tool calls to manage TeamRetro data through familiar MCP interfaces.

Key usage patterns include: authenticating with an API key, selecting the appropriate environment base URL for the TeamRetro API, and calling tools to manage entities or generate reports. You can combine multiple tools in your AI workflows to implement end-to-end automations such as automated retrospective preparation, health check analysis, or team activity reporting.

How to install

Follow these steps to install and run the TeamRetro MCP Server using the supported approaches. Ensure you have a compatible runtime environment before proceeding.

Prerequisites you will need
- Node.js installed (for running MCP server snippets and dist builds)
- pnpm or npm for dependency installation (as shown in the build and run steps)
- Access to a TeamRetro API key with the necessary permissions for the actions you intend to perform

Option 1: NPX quick start (recommended for easy setup)
- Use the following MCP configuration with your AI client to run the server on demand via NPX.

{
  "mcpServers": {
    "teamretro_mcp": {
      "command": "npx",
      "args": ["-y", "teamretro-mcp-server"],
      "env": {
        "TEAMRETRO_AUTH_TYPE": "apiKey",
        "TEAMRETRO_API_KEY": "your-api-key"
      }
    }
  }
}

Option 2: Install via Smithery (Claude Desktop)

Install the MCP server using Smithery to integrate with Claude Desktop. Run the following command in your terminal.

npx -y @smithery/cli install @adepanges/teamretro-mcp-server --client claude

Option 3: Run from source code

If you prefer to run the MCP server from source, clone the repository, install dependencies, and build the project. Then start the runtime with a direct node command.

git clone https://github.com/adepanges/teamretro-mcp-server.git
cd teamretro-mcp-server
pnpm install
pnpm run build
```

```json
{
  "mcpServers": {
    "teamretro_mcp": {
      "command": "node",
      "args": ["/path/to/teamretro-mcp-server/dist/index.js"],
      "env": {
        "TEAMRETRO_AUTH_TYPE": "apiKey",
        "TEAMRETRO_API_KEY": "your-api-key"
      }
    }
  }
}

list_users

List users with pagination, allowing you to fetch user records in chunks using offset and limit.

add_user

Add a new user or update an existing user's information by their email address, with optional name and emailAddress.

update_user

Update an existing user's details, such as their name and emailAddress, by providing the current email.

delete_user

Delete a user by their email address.

get_user

Retrieve detailed information about a single user by their email address.

list_teams

List teams with optional filtering by tags and IDs, and support for pagination.

detail_team

Get detailed information about a single team by its ID.

update_team

Update a team's details, including name and tags, by its ID.

create_team

Create a new team with a required name and optional tags and members.

delete_team

Delete a team by its ID.

list_team_members

Retrieve members of a specific team with pagination controls.

get_team_member

Fetch a team member by their email within a specific team.

update_team_member

Update a team member's details, such as name or admin status, by email within a team.

remove_team_member

Remove a team member from a team by their email.

add_team_member

Add a new team member by email with optional admin status.

list_actions

Retrieve actions with optional filtering by team tags/IDs and pagination.

create_action

Create a new action with required details like team ID, title, due date, status, and assignee.

get_action

Fetch a single action by its ID.

update_action

Update an action with new details such as title, due date, status, priority, and assignee.

delete_action

Delete an action by its ID.

list_agreements

List agreements with optional filtering by team tags/IDs and pagination.

create_agreement

Create a new agreement with team reference and title.

get_agreement

Retrieve a single agreement by its ID.

update_agreement

Update an agreement's title or team association.

delete_agreement

Delete an agreement by its ID.

list_health_checks

List health checks with optional filtering by model IDs, team tags, and team IDs, plus pagination.

get_health_check

Retrieve a single health check by its ID with optional included attributes.

delete_health_check

Delete a health check by its ID.

list_health_models

List health models with pagination.

get_health_model

Retrieve a health model by its ID.

list_retrospectives

List retrospectives with filtering by team tags/IDs and pagination.

get_retrospective

Get detailed information about a single retrospective by its ID.

delete_retrospective

Delete a retrospective by its ID.

team_activity_report

Generate a team activity report with optional filtering by tags and IDs.

team_actions_activity_report

Generate a team actions activity report and return CSV data with action statistics.

retrospective_activity_report

Generate a retrospective activity report and return CSV data with participation, ideas, comments, actions, and agreements.

health_check_activity_report

Generate a health check activity report and return CSV data with participation, comments, actions, and agreements.

team_health_latest_report

Generate a latest team health CSV report for a specific health model with date and tag filtering.

team_health_historical_report

Generate a historical team health CSV report for a specific health model with date and tag filtering.

users_report

Generate a users CSV report with account roles, team memberships, and activity statistics.