tiflux-mcp

tiflux/tiflux-mcp

3.3

If you are the rightful owner of tiflux-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The TiFlux MCP Server facilitates integration with Claude Code and other AI clients through the Model Context Protocol.

Tools
2
Resources
0
Prompts
0

TiFlux MCP Server

Model Context Protocol (MCP) server for TiFlux integration with Claude Code and other AI clients.

Features

  • Ticket Management: Get, create, update, close and list tickets with comprehensive filtering
  • Internal Communications: Create and list internal communications for tickets with file attachments
  • Client Search: Search for clients by name with automatic resolution
  • File Upload Support: Attach up to 10 files (25MB each) to internal communications
  • API Integration: Direct integration with TiFlux API v2
  • Environment Configuration: Secure configuration with environment variables
  • Comprehensive Testing: 78 automated tests with 100% mock isolation

Installation

npm install -g @tiflux/mcp

Usage

With Claude Code

Add to your MCP configuration:

{
  "tiflux": {
    "command": "npx",
    "args": ["@tiflux/mcp@latest"]
  }
}

With Other MCP Clients

npx @tiflux/mcp@latest

Via URL (HTTP Transport)

Endpoint: https://mcp.tiflux.com/mcp

claude mcp add tiflux-lambda --transport http https://mcp.tiflux.com/mcp --header "x-tiflux-api-key:APIKEY" -s project
Manual Configuration

Add to .claude/settings.json or ~/.claude.json:

{
  "mcpServers": {
    "tiflux": {
      "type": "url",
      "url": "https://mcp.tiflux.com/mcp",
      "headers": {
        "x-tiflux-api-key": "YOUR_API_KEY"
      }
    }
  }
}
Endpoints
EndpointMethodAuthDescription
/mcpGETNoServer info
/mcpPOSTYesMCP operations
/healthGETNoHealth check

Configuration

Create a .env file with your TiFlux API credentials:

# TiFlux API Configuration
TIFLUX_API_KEY=your_api_key_here

# Default values for ticket creation
TIFLUX_DEFAULT_CLIENT_ID=1
TIFLUX_DEFAULT_DESK_ID=1
TIFLUX_DEFAULT_PRIORITY_ID=1
TIFLUX_DEFAULT_CATALOG_ITEM_ID=1

Available Tools

get_ticket

Retrieve a specific ticket by ID with comprehensive information including status, priority, desk, stage, catalog, responsible, client, audit data, SLA and URLs.

Parameters:

  • ticket_number (string, required): Number of the ticket to retrieve
  • show_entities (boolean, optional): Include ALL custom fields linked to the ticket
  • include_filled_entity (boolean, optional): Include only custom fields with filled values

Returns: Comprehensive ticket information including:

  • Status (ID, name, open/closed flags)
  • Priority (ID, name)
  • Desk (ID, internal name, display name, active status)
  • Stage (ID, name, first/last stage flags, max time)
  • Service Catalog (item ID, item name, area, catalog)
  • Responsible (ID, name, email, type, technical group)
  • Client (ID, name, social reason, active status)
  • Audit (created by ID, origin, created/updated dates)
  • SLA (status, expirations, deadlines)
  • Additional info (followers, worked hours, reopens, internal/external URLs)

New in v1.4.0: Expanded fields for complete ticket metadata in a single call.

create_ticket

Create a new ticket in TiFlux.

Parameters:

  • title (string, required): Ticket title
  • description (string, required): Ticket description
  • client_id (number, optional): Client ID
  • client_name (string, optional): Client name for automatic search (alternative to client_id)
  • desk_id (number, optional): Desk ID
  • desk_name (string, optional): Desk name for automatic search (alternative to desk_id)
  • priority_id (number, optional): Priority ID
  • services_catalogs_item_id (number, optional): Service catalog item ID
  • catalog_item_name (string, optional): Catalog item name for automatic search (alternative to services_catalogs_item_id, requires desk_id or desk_name)
  • status_id (number, optional): Status ID
  • requestor_name (string, optional): Requestor name
  • requestor_email (string, optional): Requestor email
  • requestor_telephone (string, optional): Requestor phone
  • responsible_id (number, optional): Responsible user ID
  • responsible_name (string, optional): Responsible user name for automatic search (alternative to responsible_id)
  • followers (string, optional): Comma-separated follower emails

update_ticket

Update an existing ticket in TiFlux.

Parameters:

  • ticket_id (string, required): ID of the ticket to update
  • title (string, optional): New ticket title
  • description (string, optional): New ticket description
  • client_id (number, optional): New client ID
  • desk_id (number, optional): New desk ID
  • desk_name (string, optional): Desk name for automatic search (alternative to desk_id)
  • stage_id (number, optional): Stage/phase ID
  • stage_name (string, optional): Stage name for automatic search (alternative to stage_id, requires desk_id or desk_name)
  • responsible_id (number, optional): Responsible user ID (use null to unassign)
  • responsible_name (string, optional): Responsible user name for automatic search (alternative to responsible_id)
  • followers (string, optional): Comma-separated follower emails
  • services_catalogs_item_id (number, optional): Catalog item ID for updating desk with specific item
  • catalog_item_name (string, optional): Catalog item name for automatic search (alternative to services_catalogs_item_id, requires desk_id or desk_name)

Note: At least one optional field must be provided along with the ticket_id.

update_ticket_entities

Update custom fields (entities) of a ticket in TiFlux. Supports up to 50 fields per request.

Parameters:

  • ticket_number (string, required): Ticket number to update
  • entities (array, required): List of custom fields to update

Entity Object Structure:

  • entity_field_id (number, required): Custom field ID (obtained via get_ticket)
  • value (string, required): Field value. Accepted types:
    • text: string
    • text_area: string
    • currency: float as string (e.g., "150.55")
    • phone: numbers only (e.g., "47999999999")
    • email: string
    • link: URL starting with http/https/ftp
    • date: format YYYY-MM-DD
    • single_select: option ID as string
    • checkbox: boolean as string "true"/"false"
    • Use null to clear non-required fields
  • country_code (string, optional): Country code (for phone fields outside Brazil)

Example:

{
  "ticket_number": "123",
  "entities": [
    {
      "entity_field_id": 72,
      "value": "New value"
    },
    {
      "entity_field_id": 73,
      "value": "2025-01-15"
    }
  ]
}

cancel_ticket

Cancel a specific ticket in TiFlux.

Parameters:

  • ticket_number (string, required): Ticket number to be cancelled (e.g., "37", "123")

Example:

{
  "ticket_number": "84429"
}

list_tickets

List tickets with filtering options.

Parameters:

  • desk_ids (string, optional): Comma-separated desk IDs (e.g., "1,2,3")
  • desk_name (string, optional): Desk name for automatic ID resolution
  • client_ids (string, optional): Comma-separated client IDs (e.g., "1,2,3")
  • stage_ids (string, optional): Comma-separated stage IDs (e.g., "1,2,3")
  • stage_name (string, optional): Stage name (must be used with desk_name)
  • responsible_ids (string, optional): Comma-separated responsible user IDs
  • offset (number, optional): Page number (default: 1)
  • limit (number, optional): Items per page (default: 20, max: 200)
  • is_closed (boolean, optional): Include closed tickets (default: false)
  • date_type (string, optional): Date type for filtering: "created_at" (creation date, default) or "solved_in_time" (resolution/closing date)
  • start_datetime (string, optional): Start date/time filter in ISO 8601 format (e.g., "2024-05-15T00:00:00Z"). Filters tickets with date >= start_datetime
  • end_datetime (string, optional): End date/time filter in ISO 8601 format (e.g., "2024-05-15T23:59:59Z"). Filters tickets with date <= end_datetime

Note: At least one filter (desk_ids/desk_name, client_ids, stage_ids/stage_name, or responsible_ids) is required.

Date Filtering Examples:

// List tickets created in a specific date range (including closed ones)
{
  "desk_name": "Support",
  "date_type": "created_at",
  "start_datetime": "2024-01-01T00:00:00Z",
  "end_datetime": "2024-01-31T23:59:59Z",
  "is_closed": true
}

// List tickets resolved in a specific period
{
  "desk_name": "Support",
  "date_type": "solved_in_time",
  "start_datetime": "2024-01-01T00:00:00Z",
  "end_datetime": "2024-01-31T23:59:59Z",
  "is_closed": true
}

close_ticket

Close a specific ticket in TiFlux.

Parameters:

  • ticket_number (string, required): Ticket number to be closed (e.g., "37", "123")

Example:

{
  "ticket_number": "84429"
}

Success Response:

**Ticket #84429 fechado com sucesso!**

**Mensagem:** Ticket 84429 closed successfully

*Ticket fechado via API TiFlux*

create_ticket_answer

Create a new answer (client communication) in a specific ticket.

Parameters:

  • ticket_number (string, required): Ticket number where answer will be created
  • text (string, required): Answer content that will be sent to the client
  • with_signature (boolean, optional): Include user signature in the answer (default: false)
  • files (array, optional): Array of local file paths to attach (max 10 files, 40MB each)
  • files_base64 (array, optional): Array of base64 encoded files [{content: "base64...", filename: "file.pdf"}] (alternative to files, max 10 files, 40MB each)

New in v1.3.0: Support for base64 file upload via files_base64 parameter.

Example:

{
  "ticket_number": "123",
  "text": "Hello, your issue has been resolved.",
  "with_signature": true,
  "files": ["/path/to/attachment.pdf"]
}

search_client

Search for clients by name.

Parameters:

  • client_name (string, required): Client name to search (partial match supported)

search_user

Search for users by name to use as responsible in tickets.

Parameters:

  • name (string, required): User name to search (partial match supported, searches in name and email)
  • type (string, optional): User type filter (client, attendant, admin)
  • active (boolean, optional): Filter active (true) or inactive (false) users
  • limit (number, optional): Results per page (default: 20, max: 200)
  • offset (number, optional): Page number (default: 1)

Implementation Note: The TiFlux API does not support name-based filtering in the /users endpoint. This tool fetches up to 200 users from the API and performs client-side filtering by name and email. This approach ensures compatibility with the API while providing the expected search functionality.

Requirements: The API user must have the users_manage permission to access the /users endpoint.

Example:

{
  "name": "John",
  "type": "attendant",
  "active": true
}

search_stage

Search for stages of a specific desk to use in ticket updates.

Parameters:

  • desk_id (number, optional): Desk ID to search stages
  • desk_name (string, optional): Desk name for automatic search (alternative to desk_id)
  • limit (number, optional): Results per page (default: 20, max: 200)
  • offset (number, optional): Page number (default: 1)

Note: At least one parameter (desk_id or desk_name) must be provided.

Example:

{
  "desk_name": "Suporte",
  "limit": 20
}

search_catalog_item

Search for service catalog items by name within a specific desk.

Parameters:

  • desk_id (number, optional): Desk ID to search catalog items
  • desk_name (string, optional): Desk name for automatic search (alternative to desk_id)
  • catalog_item_name (string, required): Catalog item name to search (partial match supported)
  • area_id (number, optional): Service area ID to filter results
  • catalog_id (number, optional): Service catalog ID to filter results
  • limit (number, optional): Results per page (default: 20, max: 200)
  • offset (number, optional): Page number (default: 1)

Note: At least one parameter (desk_id or desk_name) must be provided along with catalog_item_name.

Example:

{
  "desk_name": "Support",
  "catalog_item_name": "Installation",
  "limit": 10
}

Internal Communications

create_internal_communication

Create a new internal communication in a ticket.

Parameters:

  • ticket_number (string, required): Ticket number where communication will be created
  • text (string, required): Communication content
  • files (array, optional): Array of local file paths to attach (max 10 files, 25MB each)
  • files_base64 (array, optional): Array of base64 encoded files [{content: "base64...", filename: "file.pdf"}] (alternative to files, max 10 files, 25MB each)

New in v1.3.0: Support for base64 file upload via files_base64 parameter.

Example:

{
  "ticket_number": "123",
  "text": "Internal communication content",
  "files": ["/path/to/file1.pdf", "/path/to/file2.png"]
}

list_internal_communications

List internal communications for a ticket.

Parameters:

  • ticket_number (string, required): Ticket number to list communications
  • offset (number, optional): Page number (default: 1)
  • limit (number, optional): Communications per page (default: 20, max: 200)

get_ticket_files

Get all files attached to a specific ticket.

Parameters:

  • ticket_number (string, required): Ticket number to retrieve files from

Returns: List of files with details including:

  • File ID, name, content type
  • File size (formatted as KB/MB/GB)
  • URL for download
  • Created date and creator information

Example:

{
  "ticket_number": "123"
}

get_internal_communication

Get a specific internal communication with full content.

Parameters:

  • ticket_number (string, required): Ticket number containing the communication
  • communication_id (string, required): ID of the internal communication to retrieve

API Endpoints Used

The MCP server integrates with the following TiFlux API v2 endpoints:

  • GET /tickets/{id} - Retrieve ticket details
  • POST /tickets - Create new tickets
  • PUT /tickets/{id} - Update existing tickets
  • PUT /tickets/{id}/entities - Update ticket custom fields
  • PUT /tickets/{ticket_number}/cancel - Cancel specific ticket
  • PUT /tickets/{ticket_number}/close - Close specific ticket
  • POST /tickets/{ticket_number}/answers - Create ticket answer (client communication)
  • GET /tickets - List tickets with filters
  • GET /clients - Search clients
  • GET /users - List users (name filtering done client-side)
  • GET /desks - Search desks
  • GET /desks/{id}/stages - Get desk stages
  • GET /desks/{id}/services-catalogs-items - Get service catalog items
  • POST /tickets/{ticket_number}/internal_communications - Create internal communication
  • GET /tickets/{ticket_number}/internal_communications - List internal communications
  • GET /tickets/{ticket_number}/internal_communications/{id} - Get specific internal communication
  • GET /tickets/{ticket_number}/files - Get ticket attached files

Development

# Clone the repository
git clone https://github.com/tiflux/tiflux-mcp.git
cd tiflux-mcp

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit .env with your credentials
# Run the server
npm start

# Run tests
npm test                    # All tests
npm run test:unit          # Unit tests only
npm run test:coverage      # Tests with coverage report

Testing

The project includes comprehensive automated testing:

  • 78 total tests with 100% pass rate
  • Complete API mocking - no external HTTP calls during testing
  • Unit tests for individual components (API, handlers, schemas)
  • Integration tests for MCP server functionality
  • Mock data fixtures for consistent test scenarios
  • Performance tests for concurrent operations

Run tests with:

npm test                 # All tests
npm run test:unit       # Unit tests only  
npm run test:integration # Integration tests only
npm run test:coverage   # Coverage report
npm run test:watch      # Watch mode
npm run test:verbose    # Detailed output

Requirements

  • Node.js >= 16.0.0
  • Valid TiFlux API credentials

License

MIT

Contributing

Issues and pull requests are welcome on GitHub.

Support

For support, please contact the TiFlux development team or create an issue on GitHub.