Teamflect MCP Server

MCP (Model Context Protocol) server for Teamflect API integration. Provides tools to interact with Teamflect's performance management features including goals, feedback, recognitions, reviews, tasks, and user management.

Features

• Goals: Get, create, update progress, and comment on goals
• Feedbacks: Get feedbacks, send feedback requests (internal and external)
• Recognitions: Get, search, and create recognitions
• Reviews: Get reviews with filtering
• Tasks: Get tasks and individual task details
• Users: Get users, get user by email, update user attributes, and get available roles

Prerequisites

• Node.js >= 18
• Teamflect API key from https://admin.teamflect.com
• MCP client (Claude Desktop or Cursor IDE)

Installation

You can use it directly with npx (no installation needed) or install it globally.

Option 1: Use with npx (Recommended - No Installation)

No installation required. Just use npx in your MCP client configuration (see Configuration section below).

Option 2: Install Globally

npm install -g teamflect-mcp-server

Option 3: Install from Source

For development or customization:

git clone <repository-url>
cd teamflect-mcp-server
npm install
npm run build

Configuration

1. Get Your API Key

Get your API key from https://admin.teamflect.com → Settings → API

2. Configure MCP Client

Claude Desktop: Edit claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor IDE: Settings (Ctrl+,) → Search "MCP" → Edit settings.json

Recommended Configuration (using npm package):

{
  "mcpServers": {
    "teamflect": {
      "command": "npx",
      "args": ["-y", "teamflect-mcp-server"],
      "env": {
        "TEAMFLECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternative Configuration (source installation only):

{
  "mcpServers": {
    "teamflect": {
      "command": "node",
      "args": ["/absolute/path/to/teamflect-mcp-server/dist/index.js"],
      "env": {
        "TEAMFLECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows path format: Use double backslashes \\ in JSON: "C:\\path\\to\\teamflect-mcp-server\\dist\\index.js"

3. Restart Your MCP Client

After configuration, completely close and restart Claude Desktop or Cursor IDE.

Updating

If using npx (recommended): Cursor automatically uses the latest published version each time it starts. No action needed - just restart Cursor after a new version is published.

If installed globally: Update manually:

npm install -g teamflect-mcp-server@latest

Then restart Cursor IDE or Claude Desktop.

If installed from source: Pull updates and rebuild:

cd /path/to/teamflect-mcp-server
git pull
npm install
npm run build

Then restart your MCP client.

Usage Examples

• "Get all users from Teamflect"
• "Get user [email protected]"
• "Get all goals"
• "Create a new goal for Q1 2025"
• "Get all feedbacks"
• "Search for recognitions"

Available Tools

Goals

• teamflect_get_goals - Get list of goals with filtering
• teamflect_get_goal - Get a specific goal by ID
• teamflect_create_goal - Create a new goal
• teamflect_update_goal_progress - Update goal progress
• teamflect_comment_goal - Add a comment to a goal

Feedbacks

• teamflect_get_feedbacks - Get list of feedbacks
• teamflect_send_feedback_request - Send internal feedback request
• teamflect_send_external_feedback_request - Send external feedback request

Recognitions

• teamflect_get_recognition - Get a specific recognition by ID
• teamflect_search_recognitions - Search recognitions
• teamflect_create_recognition - Create a new recognition

Reviews

• teamflect_get_reviews - Get list of reviews with filtering

Tasks

• teamflect_get_tasks - Get list of tasks
• teamflect_get_task - Get a specific task by ID

Users

• teamflect_get_users - Get list of users with filtering and pagination
• teamflect_get_user - Get a specific user by email
• teamflect_update_user - Update user attributes
• teamflect_get_roles - Get available user roles

Troubleshooting

Server not starting:

• Check Node.js version: node --version (should be >= 18)
• For source installation: Run npm run build and verify dist/index.js exists

Package not found:

• Verify package is published: npm view teamflect-mcp-server
• Check npm registry: npm config get registry (should be https://registry.npmjs.org/)
• Ensure you're connected to the internet

MCP client doesn't see server:

• Verify JSON syntax is valid (use https://jsonlint.com)
• For source installation: Ensure dist/index.js exists (run npm run build)
• Restart MCP client completely

Tools not working:

• Verify API key is correct and has necessary permissions
• Test API directly: curl https://api.teamflect.com/api/v1/user/getUsers -H "Authorization: Bearer YOUR_API_KEY"

Environment Variables

• TEAMFLECT_API_KEY (required): Your Teamflect API key
• TRANSPORT (optional): stdio (default) or http
• PORT (optional): Port for HTTP transport (default: 3000)

Development

npm run build    # Build the project
npm run dev      # Run in development mode with watch
npm start        # Run the server

Important: API Endpoint Guidelines

CRITICAL: Never assume API endpoints. When adding new API integrations:

1. Search the codebase first - Look for existing endpoint patterns
2. Check API documentation - Review https://api.teamflect.com/api/v1/
3. Ask if unsure - Always confirm the correct endpoint with the user before implementing

See CONTRIBUTING.md for detailed guidelines.

Publishing to npm

If you encounter 2FA authentication issues when publishing to npmjs.org, use this workaround:

1. First, logout from the command line:

   npm logout

2. Create a granular token in the npm web interface:

   • Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   • Click "Generate New Token"
   • Select "Automation" or "Publish" type
   • Check "Bypass 2FA" option
   • Copy the generated token

3. Set the token using npm config:

   npm config set //registry.npmjs.org/:_authToken npm_yournewtokenhere

4. Publish the package:

   npm publish

This workaround allows publishing without requiring 2FA OTP codes during the publish process.

API Documentation

https://api.teamflect.com/api/v1/

License

MIT