Timofi Task Management MCP Server

A Model Context Protocol (MCP) server for integrating with Timofi's task management API. This is a stateless, command-based MCP server that executes API calls and stops - no persistent server process required.

Installation

1. Generate a GitHub Personal Access Token

1. Go to: https://github.com/settings/tokens

2. Click “Generate new token” → “Generate new token (classic)”

3. Select the read:packages scope (no other permissions are required)

4. Generate the token and copy it (you won’t be able to see it again)

2. Configure Your .npmrc File

1. Open a terminal and navigate to your home directory:

npm install -g @timofi/timofi-mcp-server

2. Create a .npmrc file if it doesn’t already exist:

touch .npmrc

3. Add the following content:

@goldcode-io:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

4. Replace YOUR_GITHUB_TOKEN with the token you copied from GitHub.

3. Install the MCP Package

1. Run the following command in your terminal:

npm install -g @goldcode-io/timofi-mcp-server@latest

Installing globally (-g) ensures the package is available system-wide.

4. Generate a Timofi API Token

1. Go to your profile: https://app.timofi.com/app/profile

2. Navigate to the Developer tab

3. Click “Generate API Token”

4. Copy the generated token

5. Configure MCP in Claude Code

1. Open the .claude.json file in your home directory:

2. nano ~/.claude.json

3. Add the following inside the mcpServers section:

"timofi": {
  "command": "npx",
  "args": [
    "@goldcode-io/timofi-mcp-server"
  ],
  "env": {
    "TIMOFI_API_BASE_URL": "https://api.timofi.com",
    "EXTERNAL_TOKEN": "YOUR_TIMOFI_TOKEN"
  }
}

4. Replace YOUR_TIMOFI_TOKEN with your Timofi API token.

6. Verify the Setup

1. Open Claude Code

2. Run:

/mcp

3. Under Local MCPs, you should see timofi listed and connected

Notes

• If the MCP server does not appear, restart Claude Code and try again
• Ensure your .npmrc file is correctly configured if installation fails
• Double-check that both tokens are valid and correctly pasted

Overview

This MCP server provides access to Timofi's comprehensive task management system through external token authentication. It supports tasks, notes, statuses, roadmaps, projects, milestones, and user management operations.

Authentication

All endpoints use external token authentication via the x-external-token header. The server automatically handles system user credentials for all operations.

Environment Variables Required

TIMOFI_API_BASE_URL=https://your-timofi-instance.com
EXTERNAL_TOKEN=your-external-token-here

Important: The API expects EXTERNAL_TOKEN (not TIMOFI_EXTERNAL_TOKEN).

Available Tools

🔧 Task Management

| Tool | Description | | ---------------------- | ----------------------------- | | get_task | Get task details by ID | | create_task | Create a new task | | update_task | Update task fields | | batch_update_tasks | Batch update task status | | delete_task | Delete a task | | unarchive_task | Unarchive a task | | list_tasks_by_status | List tasks filtered by status |

📝 Task Notes

| Tool | Description | | ------------------ | ------------------------ | | get_task_notes | Get all notes for a task | | create_task_note | Add a note to a task | | update_task_note | Update an existing note |

🏷️ Task Status Management

| Tool | Description | | ---------------------------- | -------------------------------- | | get_task_statuses | List task statuses | | create_task_status | Create a new status | | update_task_status | Update a status | | batch_update_task_statuses | Batch update multiple statuses | | delete_task_status | Delete a status | | get_statuses_by_projects | Get statuses grouped by projects |

🗺️ Roadmap Management

| Tool | Description | | ------------------------------ | -------------------------------- | | get_roadmap | Get roadmap by team | | create_roadmap | Create a roadmap | | update_roadmap | Update a roadmap | | delete_roadmap | Delete a roadmap | | get_roadmap_item_report | Get roadmap item progress report | | create_roadmap_item | Create a roadmap item | | update_roadmap_item | Update a roadmap item | | delete_roadmap_item | Delete a roadmap item | | update_roadmap_item_position | Reorder roadmap items |

📊 Project & Milestone Management

| Tool | Description | | --------------------------- | --------------------------------- | | get_projects | List all projects | | get_project | Get project details | | create_project | Create a project | | update_project | Update a project | | create_project_milestones | Create milestones for a project | | get_project_milestones | List project milestones | | update_milestone | Update a milestone | | delete_milestone | Delete a milestone | | generate_milestone_stages | Generate milestone stages with AI |

👥 User Management

| Tool | Description | | -------------------- | ---------------------------- | | get_contractors | List contractors | | get_clients | List clients | | find_user_by_email | Find a user by email address |

🏢 Team Management

| Tool | Description | | ------------------------- | --------------------------------- | | get_teams | List all teams | | get_teams_by_project | Get teams for a project | | get_team_members | List team members | | discover_teams | Discover available teams | | get_roadmap_by_team | Get roadmap for a team | | get_team_user_periods | List team user assignment periods | | create_team_user_period | Assign a user to a team | | update_team_user_period | Update a team assignment | | delete_team_user_period | Remove a user from a team |

Implementation Notes

Stateless Design

• No persistent server process
• Execute API call and terminate
• Suitable for command-line tools and automation scripts

Authentication Pattern

All requests automatically include system user credentials:

{
  "id": 0,
  "fullName": "External System",
  "email": "[email protected]",
  "rolesCodes": [],
  "permissions": []
}

Caching

External endpoints include intelligent caching:

• Task lists: 15 minutes
• Task details: 1 hour
• Task statuses: 30 minutes - 1 hour
• User lists: 2 hours

Error Handling

• Proper HTTP status codes
• Detailed error messages
• Graceful degradation for cache operations

Usage Examples

Task Management

# Get task details
GET ${TIMOFI_API_BASE_URL}/api/tasks/external/123

# Create new task
POST ${TIMOFI_API_BASE_URL}/api/tasks/external
{
  "title": "Implement feature X",
  "description": "Add new functionality",
  "teamId": 1,
  "assignedToId": 5,
  "statusId": 1
}

# Update task
PATCH ${TIMOFI_API_BASE_URL}/api/tasks/external/123
{
  "title": "Updated title",
  "completed": true
}

Roadmap Management

# Get team roadmap
GET ${TIMOFI_API_BASE_URL}/api/roadmap/external?teamId=1

# Create roadmap item
POST ${TIMOFI_API_BASE_URL}/api/roadmap/external/item
{
  "title": "Q1 Feature Release",
  "roadmapId": 1,
  "position": 1
}

User Queries

# Get contractors
GET ${TIMOFI_API_BASE_URL}/api/users/external/contractors

# Find user by email
GET ${TIMOFI_API_BASE_URL}/api/users/external/[email protected]

Environment Variables

The MCP server requires these environment variables (configured through your AI tool):

| Variable | Description | Example | | --------------------- | -------------------------------- | ------------------------ | | TIMOFI_API_BASE_URL | Base URL of your Timofi instance | https://api.timofi.com | | EXTERNAL_TOKEN | External authentication token | ext_abc123... |

Request Headers

All API requests automatically include:

x-external-token: ${EXTERNAL_TOKEN}
Content-Type: application/json

Quick Start

1. Install the package:

   npm install -g @timofi/timofi-mcp-server

2. Configure your AI tool with the MCP server (see configuration examples above)

3. Start using Timofi commands in your AI conversations:

   • "Create a task for implementing user authentication"
   • "Show me all tasks assigned to John"
   • "Update the roadmap for Q1 features"
   • "List all available contractors"

Security

• External token authentication required
• System-level access with controlled permissions
• Audit trails maintained for all operations
• Rate limiting and caching to prevent abuse

Integration Benefits

• Complete task lifecycle management
• Team collaboration features
• Project milestone tracking
• User and team management
• Comprehensive reporting capabilities
• Real-time status updates

Development

For development and testing:

# Clone the repository
git clone <your-mcp-server-repo>
cd timofi-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Test locally
npx . --help