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

Quick Install (macOS, AirLST team)

The AirLST MCP Installer app handles everything automatically: installs uv, configures Claude Desktop, and sets up Troi (and optionally Pipedrive) with a guided UI.

Download AirLST MCP Installer.app from your team
Double-click to run — follow the prompts to enter your Troi credentials
Restart Claude Desktop (Cmd+Q, then reopen)

To compile the installer from source:

osacompile -o "AirLST MCP Installer.app" install-airlst-mcp.applescript

Manual Setup

1. Install

pip install troi-mcp

2. Get your Troi API key

Troi → Menu (top left) → Sicherheitscenter → API v2 - Basic → copy the Token.

The Sicherheitscenter shows 3 sections — you only need the token from the first one (API v2 - Basic). The server uses HTTP Basic Auth (TROI_USER + TROI_API_KEY).

3. Add to your MCP client config

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

{
  "mcpServers": {
    "troi": {
      "command": "uvx",
      "args": ["--upgrade", "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": ["--upgrade", "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:

Call without confirmed → server returns a preview of what would happen, no API call is made
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

Metadata

Release files for troi-mcp 1.3.24

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for troi-mcp 1.3.24
File	Size	Uploaded	Provenance
troi_mcp-1.3.24.tar.gz	111.5 kB	Mar 27, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for troi-mcp 1.3.24
File	Interpreter	ABI	Platform	Reset
troi_mcp-1.3.24-py3-none-any.whl 59.6 kB Mar 27, 2026 Without provenance	Python 3	none	any	Details

Total release size: 171.1 kB

Release files / troi_mcp-1.3.24.tar.gz

Download URL	troi_mcp-1.3.24.tar.gz
Size	111.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`7bf50757c3946d20df8dcd22265584a27393db752fc1b7d1e5bc101d836a0fd2`
BLAKE2b-256 checksum How to use checksums	`2cba8a5df0ad7226453a34fcf648bc3d39a24a307a996f721c24b6d7022a1ffc`
Upload date	Mar 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.7 {"installer":{"name":"uv","version":"0.10.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / troi_mcp-1.3.24-py3-none-any.whl

Download URL	troi_mcp-1.3.24-py3-none-any.whl
Size	59.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0a96acc28f4567031873defe7dd8ac8cc7e26c24b8ce20455995f7558427422a`
BLAKE2b-256 checksum How to use checksums	`d2a25d1b8f0e4284b25b11fee7363eaad147df6922b6c85c86172d7eb45ec070`
Upload date	Mar 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.7 {"installer":{"name":"uv","version":"0.10.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Security for troi-mcp 1.3.24

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.