troi-mcp 1.0.0

MCP server that connects Claude Desktop to Troi project management & time tracking

troi-mcp

MCP server that connects AI assistants to Troi project management, time tracking, and offer creation. Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).

Features

• 49 tools covering projects, offers, time tracking, contacts, customers, and more
• Server-enforced permission layer — all write operations return a preview first; re-call with confirmed=true to execute
• Irreversible action protection — offer number generation and approval submission get extra warnings
• Price list integration — create offers directly from your Troi price list
• Compound tools — troi_create_offer builds a complete project with phases and positions in one call

Setup

1. Install

pip install troi-mcp

2. Get your Troi API key

Troi → Profile (top right) → API → Copy key

3. Add to your MCP client config

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "troi": {
      "command": "uvx",
      "args": ["troi-mcp"],
      "env": {
        "TROI_URL": "https://yourcompany.troi.software",
        "TROI_USER": "j.doe",
        "TROI_API_KEY": "your-api-key",
        "TROI_CLIENT_ID": "1"
      }
    }
  }
}

Claude Code — add to .mcp.json in your project root:

{
  "mcpServers": {
    "troi": {
      "command": "uvx",
      "args": ["troi-mcp"],
      "env": {
        "TROI_URL": "https://yourcompany.troi.software",
        "TROI_USER": "j.doe",
        "TROI_API_KEY": "your-api-key",
        "TROI_CLIENT_ID": "1"
      }
    }
  }
}

Note: TROI_USER is your Troi login name (e.g. j.doe), not your email address. TROI_CLIENT_ID is usually 1 (single-tenant setups).

4. Restart your MCP client

The Troi tools will be available automatically.

Available Tools (49)

Projects & Subprojects

Tool	Description
troi_list_projects	List/search projects with filters
troi_get_project	Get project details
troi_create_project	Create a new project
troi_update_project	Update project properties
troi_delete_project	Delete a project
troi_list_subprojects	List subprojects (phases)
troi_get_subproject	Get subproject details
troi_create_subproject	Create a subproject
troi_update_subproject	Update a subproject
troi_delete_subproject	Delete a subproject

Calculation Positions & Price Lists

Tool	Description
troi_list_positions	List calculation positions (budget items)
troi_get_position	Get position details
troi_create_position	Create a position manually
troi_create_position_from_pricelist	Create a position from a price list item
troi_update_position	Update a position
troi_delete_position	Delete a position
troi_list_pricelist_groups	List available price lists
troi_list_pricelist_items	List items in a price list

Offers & Documents

Tool	Description
troi_create_offer	Create a complete offer (project + phases + positions) in one call
troi_get_offer_summary	Get offer summary with totals
troi_list_documents	List documents (offers, invoices)
troi_get_document	Get document details
troi_download_offer_pdf	Download offer as PDF
troi_generate_offer_number	Assign an offer number and download PDF (irreversible)
troi_start_approval	Submit offer for approval (irreversible)
troi_get_approval_info	Get available approvers for a document

Time Tracking

Tool	Description
troi_list_time_entries	List booked hours
troi_get_time_entry	Get time entry details
troi_create_time_entry	Book time
troi_update_time_entry	Update a time entry
troi_delete_time_entry	Delete a time entry

Contacts & Customers

Tool	Description
troi_list_contacts	List/search contacts
troi_get_contact	Get contact details
troi_create_contact	Create a contact (company or person)
troi_update_contact	Update a contact
troi_list_customers	List customers (Auftraggeber)
troi_get_customer	Get customer details
troi_create_customer	Create a customer linked to a contact
troi_update_customer	Update a customer
troi_create_customer_with_contact	Create company contact + customer in one call

Reference Data

Tool	Description
troi_list_employees	List employees
troi_get_employee	Get employee details
troi_list_clients	List clients (Mandanten)
troi_get_client	Get client details
troi_list_absences	List absences (vacation, sick days)
troi_list_calendar_events	List calendar events
troi_list_project_types	List project types
troi_list_project_statuses	List project statuses
troi_list_units	List units (hours, days, etc.)
troi_list_booking_years	List booking years

Permission Layer

All 21 write operations are server-enforced:

1. Call without confirmed → server returns a preview of what would happen, no API call is made
2. Call with confirmed: true → server executes the operation

Two tools are classified as irreversible and display extra warnings:

• troi_generate_offer_number — assigns a permanent offer number
• troi_start_approval — submits a document for approval

This works with any MCP client, no special sampling or UI support required.

License

MIT