TeamMatrix MCP Server

A Model Context Protocol (MCP) server that wraps the TeamMatrix REST API, giving AI agents structured tools to manage teams, members, skill matrices, surveys, and polls without writing raw HTTP calls.

For users

This is the main installation path for regular users of the published npm package.

Prerequisites

• Node.js 18 or newer
• A running TeamMatrix instance
• A valid API key (generate one from Settings → Security in the TeamMatrix UI)

Run directly from npm

You can run the server without cloning the repository:

TEAMMATRIX_API_URL=http://localhost:8001 \
TEAMMATRIX_API_KEY=sf_live_xxx \
npx -y teammatrix-mcp

You can also install it globally if you prefer:

npm install -g teammatrix-mcp

Then run:

TEAMMATRIX_API_URL=http://localhost:8001 \
TEAMMATRIX_API_KEY=sf_live_xxx \
teammatrix-mcp

Claude Code CLI

Recommended if you use Claude Code (claude CLI). Register the server once:

claude mcp add teammatrix \
  -e TEAMMATRIX_API_URL=http://localhost:8001 \
  -e TEAMMATRIX_API_KEY=sf_live_xxx \
  -- npx -y teammatrix-mcp

Verify the server is connected:

/mcp

Claude Code will list teammatrix as an active MCP server with all its tools available.

Claude Desktop

Add the following block to ~/.claude/claude_desktop_config.json (create the file if it does not exist):

{
  "mcpServers": {
    "teammatrix": {
      "command": "npx",
      "args": ["-y", "teammatrix-mcp"],
      "env": {
        "TEAMMATRIX_API_URL": "http://localhost:8001",
        "TEAMMATRIX_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Restart Claude Desktop after saving. The TeamMatrix tools will appear in the tool picker.

Environment variables

| Variable | Required | Description | |---|---|---| | TEAMMATRIX_API_URL | yes | Base URL of the TeamMatrix instance, e.g. http://localhost:8001 | | TEAMMATRIX_API_KEY | yes | Bearer API key starting with sf_live_ |

Available tools

Teams

| Tool | Description | |---|---| | list_teams | List accessible teams with optional search, status filter, and pagination | | get_team | Get full details of a single team | | create_team | Create a new team | | update_team | Partially update a team's name, description, or visibility flags | | delete_team | Soft-delete a team |

Members

| Tool | Description | |---|---| | list_members | List team members, optionally filtered by status or lead role | | get_member | Get details of a single team member | | add_member | Add a user to a team by email, user_id, or username | | update_member | Update a member's display name, lead status, or active status | | remove_member | Remove a member from a team (soft delete) |

Matrices

| Tool | Description | |---|---| | list_team_matrices | List skill matrix templates assigned to a team | | assign_matrix | Assign a skill matrix template to a team | | get_team_matrix | Get the full structure of an assigned matrix (groups, levels, rows, tasks) | | update_matrix_assignment | Change the display order position of a matrix in the team list | | unassign_matrix | Remove a matrix template from a team | | list_member_progress | Get a member's skill progress across all tasks | | update_task_progress | Update a specific task's progress status for a member |

Surveys (Team Healthcheck / Maturity)

| Tool | Description | |---|---| | list_survey_templates | List available survey templates | | get_survey_template | Get a template's full block and question structure | | list_team_surveys | List surveys for a team, filtered by status or date range | | create_survey | Create a survey draft from a template | | get_survey | Get survey details and completion stats | | launch_survey | Launch a draft survey (sends invitations asynchronously) | | close_survey | Manually close an active survey | | reopen_survey | Reopen a closed survey with an optional new deadline | | remind_survey | Queue a manual reminder for incomplete participants | | list_survey_participants | List participants and their completion status | | get_survey_results | Get aggregated results: scores, heatmap, AI summary, baseline history |

Polls (Interviews / 360 Assessments)

| Tool | Description | |---|---| | list_poll_templates | List available poll/interview templates | | instantiate_poll_template | Create a poll draft from a template | | list_polls | List manageable polls with status filter and pagination | | create_poll | Create a new poll draft from scratch | | get_poll | Get poll details | | update_poll | Partially update a poll draft's settings | | delete_poll | Delete a poll draft | | list_poll_questions | List all questions in a poll | | add_poll_question | Add a question (text, scale, single, or multi type) | | update_poll_question | Update an existing question | | delete_poll_question | Delete a question | | list_poll_participants | List participants with roles and voted status | | add_poll_participant | Add a participant with voter/viewer flags and role label | | remove_poll_participant | Remove a participant from a poll draft | | launch_poll | Launch a poll draft (sends invitations asynchronously) | | get_poll_results | Get aggregated results by role and group |

Users & Auth

| Tool | Description | |---|---| | list_users | Search accessible users by name or email | | get_current_user | Get the identity associated with the current API key | | get_api_key_info | Get API key metadata (prefix, creation date, last used) |

For developers

This section is for contributors working with the source code from the repository or a downloaded source archive. Regular users of the npm package usually do not need these steps.

Local source setup

cd mcp
npm install
npm run build

After any source change, re-run npm run build to refresh dist/.

Testing with MCP Inspector from source

The fastest way to verify the local source build works is the MCP Inspector:

TEAMMATRIX_API_URL=http://localhost:8001 \
TEAMMATRIX_API_KEY=sf_live_xxx \
npx @modelcontextprotocol/inspector node dist/index.js

Open the URL printed in the terminal (default: http://localhost:6274). You will see all registered tools listed in the sidebar. Click any tool, fill in parameters, and execute. The raw JSON response is shown inline.