@timofi/timofi-mcp-server

v0.3.0

Published

25 days ago

MCP server for Timofi task management API integration

0High
0Medium
0Low

lucas-timofi

mcp timofi task-management ai claude

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

Go to: https://github.com/settings/tokens
Click “Generate new token” → “Generate new token (classic)”
Select the read:packages scope (no other permissions are required)
Generate the token and copy it (you won’t be able to see it again)

2. Configure Your .npmrc File

Open a terminal and navigate to your home directory:

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

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

touch .npmrc

Add the following content:

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

Replace YOUR_GITHUB_TOKEN with the token you copied from GitHub.

3. Install the MCP Package

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

Go to your profile: https://app.timofi.com/app/profile
Navigate to the Developer tab
Click “Generate API Token”
Copy the generated token

5. Configure MCP in Claude Code

Open the .claude.json file in your home directory:
nano ~/.claude.json
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",
    "TIMOFI_TENANT_ID": "YOUR_TIMOFI_TENANT_ID",
    "TIMOFI_ENVIRONMENT": "production"
  }
}

Replace the token and tenant placeholders with your Timofi values.

6. Verify the Setup

Open Claude Code
Run:

/mcp

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
TIMOFI_TENANT_ID=your-tenant-uuid-here
TIMOFI_ENVIRONMENT=development

Important: The API expects EXTERNAL_TOKEN (not TIMOFI_EXTERNAL_TOKEN).

Available Tools

Version 0.2.0 exposes only the four full-page-control tools below.

Older named shortcuts are no longer registered because they bypassed the shared approval and audit gate.

Full Timofi Page Control

| Tool | Description | | --- | --- | | list_timofi_pages | List controlled pages, live actions, risk levels, and excluded human-only pages | | list_timofi_page_actions | List live actions for one page | | list_timofi_mcp_audit_log | Review tenant-scoped MCP attempts and results without payloads or passphrases | | run_timofi_page_action | Run one listed action through Timofi's existing validation and permission checks |

Money, identity, messaging, subscription, contract, queue, admin, and destructive actions require the Timofi approval passphrase.

The MCP asks for the passphrase inside the conversation, and Timofi combines it with a short-lived one-time challenge bound to the exact tenant, path, query, and payload.

Use separate passphrase hashes and separate MCP entries for development and production; Timofi rejects an MCP whose TIMOFI_ENVIRONMENT does not match the API.

Legacy tool reference

The named tools below remain documented for migration only and are not registered in version 0.2.0.

🔧 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 |

📄 Contract Management

| Tool | ----------------------------------------- | list_contracts | count_contracts | get_contract | get_contract_timeline | get_contract_filters | get_assignable_contract_users | create_contract | batch_create_contracts | update_contract | update_contract_advanced | update_contract_effective_date | unarchive_contract | delete_contract | send_contract_reminder | resend_contract | get_contract_version | update_contract_version_effecti | list_contract_templates | count_contract_templates | get_contract_template_types | get_contract_template | create_contract_template | update_contract_template | delete_contract_template | unarchive_contract_template | list_contract_template_categories | create_contract_template_category | update_contract_template_category | delete_contract_template_category | create_contract_event | list_contract_event_types | manage_contract_event_types | list_contract_alerts | list_contract_alert_contractors | Description | | ----------------------------------------------------- | | List/search contracts (positions) grouped by contractor | | Count contracts matching filters | | Get a contract's full details | | Get a contract's version/activity timeline | | Get name/email filter options for the contracts list | | List users assignable to a contract | | Create a contract for a user from a template | | Create multiple contracts at once | | Update a contract (creates a new version) | | Advanced/granular contract update | | Update a contract's effective date | | Restore a deleted/archived contract | | Soft-delete (archive) a contract | | Email a user a reminder about a pending contract | | Resend a contract email to a user | | Get a contract version's details and changes | ve_date | Update a specific version's effective date | | List contract templates | | Count contract templates matching filters | | List available contract template types | | Get a contract template by ID | | Create a contract template | | Update a contract template | | Soft-delete a contract template | | Restore a deleted contract template | | List contract template categories | | Create a contract template category | | Update a contract template category | | Delete a contract template category | | Create a recurring event/reminder tied to a contract | | List available contract event types | | Add or remove a contract event type | | List upcoming contract alerts (events) | | List users with active contracts and events |

Note: PDF generation (preview/sign/view), the end-user accept flow, and the public timestamp webhook are intentionally not exposed — they depend on an end-user identity, KMS encryption, and an external PDF service.

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... | | TIMOFI_TENANT_ID | Tenant UUID sent with every call | 00000000-... | | TIMOFI_ENVIRONMENT | Environment lock | development |

Request Headers

All API requests automatically include:

x-external-token: ${EXTERNAL_TOKEN}
x-tenant-id: ${TIMOFI_TENANT_ID}
x-timofi-mcp-environment: ${TIMOFI_ENVIRONMENT}
Content-Type: application/json

Quick Start

Install the package:

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

Configure your AI tool with the MCP server (see configuration examples above)
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