TeamRetro MCP Server
A Model Context Protocol (MCP) server that provides AI-powered integration with TeamRetro's platform. This server acts as a bridge between AI clients and TeamRetro's official API, enabling seamless interaction with team management, retrospectives, health checks, and other TeamRetro features through standardized MCP tools.
Key features:
- Complete TeamRetro API coverage with 20+ tools for managing teams, users, actions, and more
- Simplified AI client integration through standardized MCP interfaces
- Built-in pagination and filtering support for efficient data handling
- Secure API authentication handling and environment configuration
- Comprehensive documentation and easy setup options
Whether you're building AI-powered team analytics, automated retrospective management, or integrating TeamRetro into your AI workflow, this MCP server provides the foundation you need.
Important Notes
Unofficial MCP Server
This MCP server is an unofficial community-developed interface to TeamRetro's services. While not developed or endorsed by TeamRetro, it provides standardized access to their platform.
Official API Integration
The server connects directly to TeamRetro's official public API:
- Uses documented endpoints from TeamRetro's API specifications
- Maintains full API compliance and version tracking
- Implements all required authentication methods
- Preserves original API responses without modification
API Documentation Source
All API endpoints and functionality are based on TeamRetro's official documentation:
- API Help Article: https://help.teamretro.com/article/320-teamretro-api
- API Specifications: https://groupmap.stoplight.io/docs/teamretro/
- Implementation strictly follows the public API specifications
- Any changes to the TeamRetro API may affect this MCP server's functionality
How to Use
NPX (Recommended, Easy Setup)
{
"mcpServers": {
"teamretro-mcp-server": {
"command": "npx",
"args": ["-y", "teamretro-mcp-server"],
"env": {
"TEAMRETRO_AUTH_TYPE": "apiKey",
"TEAMRETRO_API_KEY": "your-api-key"
}
}
}
}
Installing via Smithery
To install TeamRetro MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @adepanges/teamretro-mcp-server --client claude
From Source Code
- Clone the repository, install dependencies, and build the project:
git clone https://github.com/adepanges/teamretro-mcp-server.git
cd teamretro-mcp-server
pnpm install
pnpm run build
Running in AI Client
- Configure the AI client with the following settings:
{
"mcpServers": {
"teamretro-mcp-server": {
"command": "node",
"args": ["/path/to/teamretro-mcp-server/dist/index.js"],
"env": {
"TEAMRETRO_AUTH_TYPE": "apiKey",
"TEAMRETRO_API_KEY": "your-api-key"
}
}
}
}
Running with Inspector
- Configure the environment variables by copying
.env.exampleto.envand modifying it according to your needs. - Run the server with inspector:
pnpm run inspector
Environment Variables Examples
Base URL
The base URL for the TeamRetro API can be set using the TEAMRETRO_BASE_URL environment variable. By default, it is set to https://api.teamretro.com.
{
"env": {
"TEAMRETRO_BASE_URL": "https://api.teamretro.com"
}
}
API Key Authentication
{
"env": {
"TEAMRETRO_AUTH_TYPE": "apiKey",
"TEAMRETRO_API_KEY": "your-api-key"
}
}
Available Tools
The server provides the following tools:
Users
list_users: List users with pagination using offset and limit parameters to control the number of results returnedadd_user: Add a new user or update an existing user's information by their email address, specifying optional name and emailAddressupdate_user: Update an existing user's details, such as their name and emailAddress, by providing their current emaildelete_user: Delete a user by their email addressget_user: Retrieve detailed information about a single user by their email address
Teams
list_teams: List teams from TeamRetro with filtering by tags and IDs, and pagination using offset and limit parametersdetail_team: Retrieve detailed information about a single team by its unique IDupdate_team: Update an existing team's details, such as its name and associated tags, by providing the team's IDcreate_team: Create a new team with a required name, and optional tags and membersdelete_team: Delete an existing team by its ID
Team Members
list_team_members: Retrieve a list of team members for a specified team ID with pagination controls for offset and limitget_team_member: Fetch a team member by their email address within a specified teamupdate_team_member: Update a team member's details, such as their name or team admin status, by their email address within a specified teamremove_team_member: Remove a team member from a team by their email addressadd_team_member: Add a new team member to a team by their email address, with optional specification of team admin status
Actions
list_actions: Retrieve a list of actions from TeamRetro with optional filtering by team tags and team IDs, and pagination controls for offset and limitcreate_action: Create a new action in TeamRetro with required details such as team ID, title, due date, completion status, and assigned userget_action: Fetch a single action by its unique ID from TeamRetroupdate_action: Update an existing action in TeamRetro with new details such as title, due date, completion status, priority, and assigned userdelete_action: Delete an existing action from TeamRetro by its action ID
Agreements
list_agreements: List agreements from TeamRetro with optional filtering by team tags and team IDs, as well as pagination controlscreate_agreement: Create a new agreement in TeamRetro by specifying the team it belongs to and its titleget_agreement: Retrieve a single agreement by its unique identifierupdate_agreement: Update an existing agreement's details such as its title or associated teamdelete_agreement: Delete an existing agreement by specifying its unique identifier
Health Checks
list_health_checks: List health checks from TeamRetro with optional filtering by health model IDs, team tags, and team IDs, as well as pagination controlsget_health_check: Retrieve a single health check by its unique identifier with optional attributes to includedelete_health_check: Delete an existing health check by specifying its unique identifier
Health Models
list_health_models: List health models from TeamRetro with pagination controlsget_health_model: Retrieve a single health model by its unique identifier
Retrospectives
list_retrospectives: List retrospectives from TeamRetro with filtering by team tags and IDs, and pagination using offset and limit parametersget_retrospective: Retrieve detailed information about a single retrospective by its unique IDdelete_retrospective: Delete an existing retrospective by its ID
Reports
team_activity_report: Generate a team activity report from TeamRetro with filtering by team tags and team IDsteam_actions_activity_report: Generate a team actions activity report from TeamRetro with filtering by team tags and team IDs. Returns CSV data with action statistics including open, completed, and overdue action counts grouped by age rangesretrospective_activity_report: Generate a retrospective activity report from TeamRetro with filtering by date range, team tags and team IDs. Returns CSV data with retrospective statistics including participation rate, idea count, comment count, action count, and agreement counthealth_check_activity_report: Generate a health check activity report from TeamRetro with filtering by date range, team tags and team IDs. Returns CSV data with health check statistics including participation rate, comment count, action count, and agreement countteam_health_latest_report: Generate a team health (latest) report from TeamRetro for a specific health model with filtering by date range, team tags and team IDs. Returns CSV data with latest team health scores including health dimensionsteam_health_historical_report: Generate a team health (historical) report from TeamRetro for a specific health model with filtering by date range, team tags and team IDs. Returns CSV data with historical team health scores including health dimensionsusers_report: Generate a users report from TeamRetro with filtering by team tags and team IDs. Returns CSV data with user information including account roles, team memberships, and activity statistics
Changelog
For a detailed list of changes and updates, see CHANGELOG.md.