TANSS MCP Server

A comprehensive Model Context Protocol (MCP) server for the TANSS API, providing seamless integration with AI assistants like Claude or n8n.

---

What is this?

The TANSS MCP Server bridges the gap between AI assistants (like Claude/n8n) and the TANSS ticket management system. It exposes 238 API endpoints through 237 tools that can be called by AI assistants to:

• 🎫 Create and manage tickets
• 📞 Handle phone calls and call assignments
• 💬 Manage chats and communications
• 🖥️ Track IT assets (PCs, peripherals, components)
• 👥 Manage employees and companies
• ⏱️ Track time and timestamps
• 📊 Create offers and invoices
• 🔧 Handle remote support sessions
• 📈 Monitor systems and devices
• And much more!

---

Features

✅ 238 API endpoints covering all TANSS functionality
✅ 237 tools (e.g., create_ticket)
✅ Dual transport modes: stdio and SSE (HTTP)
✅ Role-based authentication: Support for 6 different token types
✅ Automatic token management: Bearer prefix handling and role-specific token prioritization

---

Quick Start

Prerequisites

• Python 3.8+
• TANSS account with API access
• API token from TANSS

Installation

1. Clone the repository

git clone <repository-url>
cd tanss-mcp

2. Install dependencies

pip install -r requirements.txt

3. Configure the server

Create config.ini from the example:

cp config.ini.example config.ini

Edit config.ini and add your TANSS credentials:

[tanss]
base_url = https://your-tanss-instance.com/backend/
api_token = your_api_token_here

[credentials]
username = your_username
password = your_password

4. Start the server

For Claude Desktop (stdio mode):

python3 server.py --mode stdio

For web clients (SSE mode):

python3 server.py --mode sse --host 0.0.0.0 --port 3001

---

Configuration

Basic Configuration

Minimal config.ini:

[tanss]
base_url = https://your-tanss.com/backend/
api_token = your_access_token

[sse]
host = 127.0.0.1
port = 3001

Advanced Configuration with Role-Specific Tokens

For enhanced security and permissions, configure role-specific tokens:

[tanss]
base_url = https://your-tanss.com/backend/
api_token = your_main_token

# Optional: Role-specific tokens for specialized operations
erp_api_token = Bearer your_erp_token
phone_api_token = Bearer your_phone_token
remote_support_api_token = Bearer your_remote_support_token
monitoring_api_token = Bearer your_monitoring_token
device_management_api_token = Bearer your_device_mgmt_token
timestamp_api_token = Bearer your_timestamp_token

[sse]
host = 192.168.0.153
port = 3001
reload = false
log_level = info

[credentials]
username = your_username
password = your_password

---

Usage

With Claude Desktop

Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "tanss": {
      "command": "python3",
      "args": ["/absolute/path/to/tanss-mcp/server.py"],
      "cwd": "/absolute/path/to/tanss-mcp"
    }
  }
}

Restart Claude Desktop, and you'll have access to all TANSS tools!

As SSE Server

# Start server
python3 server.py --mode sse --host 0.0.0.0 --port 3001

# The server will be available at:
# SSE endpoint: http://your-host:3001/sse
# Messages endpoint: http://your-host:3001/messages

Getting Your API Token

Use the login tool or the test script:

# Start SSE server first
python3 server.py --mode sse

# In another terminal, test login
python3 test_login.py

This will generate access and refresh tokens you can use in config.ini.

---

Available Tools

The server provides 237 human-friendly tools across 41 categories.

Most Common Tools

🎫 Ticket Management (37 tools)

• create_ticket - Create a new ticket
• get_ticket - Get ticket details
• update_ticket - Update an existing ticket
• delete_ticket - Delete a ticket
• get_my_tickets - Get your assigned tickets
• get_all_tickets - Get all tickets
• get_company_tickets - Get tickets for a company
• add_ticket_comment - Add a comment to a ticket
• get_ticket_history - View ticket change history
• upload_ticket_file - Upload a file to a ticket

⏱️ Time Tracking (15 tools)

• create_timestamp - Clock in/out or log time
• get_timestamps - Get time records
• close_day - Close the day for time tracking
• get_timestamp_statistics - Get time statistics

💬 Chats (10 tools)

• create_chat - Start a new chat
• send_chat_message - Send a message
• close_chat - Close a chat
• reopen_chat - Reopen a closed chat
• add_chat_participant - Add someone to a chat

📞 Phone Calls (8 tools)

• create_call - Log a phone call
• get_my_calls - Get your calls
• identify_caller - Identify a caller by phone number
• assign_call_to_employee - Assign a call

🔧 Remote Support (9 tools)

• create_remote_support - Create a remote support session
• list_remote_supports - List all remote support sessions
• assign_device_to_remote_support - Link a device
• assign_employee_to_remote_support - Assign a technician

💼 ERP Integration (15 tools)

• get_company_employees - Get employees of a company
• get_company_departments - Get departments
• get_ticket_types - Get available ticket types
• get_ticket_statuses - Get available ticket statuses
• create_invoice - Create an invoice
• create_customer - Create a customer

🖥️ IT Asset Management

• create_pc / update_pc / delete_pc - Manage computers
• create_peripheral / update_peripheral - Manage peripherals
• create_component / update_component - Manage components
• get_operating_system - Get OS information

📋 Offers & Quotes (13 tools)

• create_offer - Create a new offer/quote
• update_offer - Update an offer
• get_offer_template - Get offer templates

🔐 Authentication

• login - Login and get API tokens

Complete Tool List

Total Tools: 237

Tool Name	Category
get_ticket	Ticket Operations
create_ticket	Ticket Operations
update_ticket	Ticket Operations
delete_ticket	Ticket Operations
get_ticket_history	Ticket Operations
add_ticket_comment	Ticket Operations
get_my_tickets	Ticket Lists
get_all_tickets	Ticket Lists
get_company_tickets	Ticket Lists
get_technician_tickets	Ticket Lists
get_repair_tickets	Ticket Lists
get_project_tickets	Ticket Lists
get_tickets_by_role	Ticket Lists
get_unidentified_tickets	Ticket Lists
get_admin_tickets	Ticket Lists
update_ticket_list	Ticket Lists
get_ticket_document	Ticket Content
get_ticket_screenshot	Ticket Content
upload_ticket_file	Ticket Content
get_ticket_states	Ticket States
create_ticket_state	Ticket States
update_ticket_state	Ticket States
delete_ticket_state	Ticket States
get_call	Phone Calls
create_call	Phone Calls
update_call	Phone Calls
get_call_assignments	Phone Calls
assign_call_to_employee	Phone Calls
unassign_call_from_employee	Phone Calls
identify_caller	Phone Calls
send_call_notification	Phone Calls
get_my_calls	User Phone Calls
update_my_call	User Phone Calls
identify_my_caller	User Phone Calls
get_remote_support	Remote Support
create_remote_support	Remote Support
list_remote_supports	Remote Support
update_remote_support	Remote Support
delete_remote_support	Remote Support
get_remote_support_devices	Remote Support
assign_device_to_remote_support	Remote Support
unassign_device_from_remote_support	Remote Support
get_remote_support_employees	Remote Support
assign_employee_to_remote_support	Remote Support
unassign_employee_from_remote_support	Remote Support
get_monitoring_ticket	Monitoring
create_monitoring_ticket	Monitoring
update_monitoring_ticket	Monitoring
get_monitoring_groups	Monitoring
assign_monitoring_group	Monitoring
unassign_monitoring_group	Monitoring
get_tickets_from_monitoring_group	Monitoring
get_company_departments	ERP Integration
get_company_employees	ERP Integration
get_department_employees	ERP Integration
get_employee_departments	ERP Integration
search_company_by_id	ERP Integration
get_ticket_statuses	ERP Integration
get_ticket_types	ERP Integration
get_company_categories	ERP Integration
create_company_category	ERP Integration
get_customers	ERP Integration
create_customer	ERP Integration
get_invoices	ERP Integration
create_invoice	ERP Integration
create_erp_ticket	ERP Integration
upload_ticket_file_erp	ERP Integration
get_timestamps	Time Tracking
create_timestamp	Time Tracking
update_timestamp	Time Tracking
get_timestamp_info	Time Tracking
get_timestamp_statistics	Time Tracking
get_pause_configs	Time Tracking
create_pause_config	Time Tracking
update_pause_config	Time Tracking
delete_pause_config	Time Tracking
get_day_closing	Time Tracking
create_day_closing	Time Tracking
delete_day_closing	Time Tracking
close_day	Time Tracking
update_day	Time Tracking
set_employee_initial_balance	Time Tracking
get_chat	Chats
create_chat	Chats
update_chat	Chats
get_chat_close_requests	Chats
close_chat	Chats
update_chat_close	Chats
reopen_chat	Chats
send_chat_message	Chats
add_chat_participant	Chats
remove_chat_participant	Chats
get_offer	Offers
create_offer	Offers
update_offer	Offers
update_offers	Offers
delete_offer	Offers
get_offer_template	Offers
create_offer_template	Offers
update_offer_template	Offers
delete_offer_template	Offers
get_erp_selection	Offers
create_erp_selection	Offers
update_erp_selection	Offers
delete_erp_selection	Offers
get_material_picker	Offers
get_availability	Availability
get_technicians	Employees
create_employee	Employees
get_tag	Tags
create_tag	Tags
update_tag	Tags
delete_tag	Tags
get_tag_assignments	Tags
assign_tag	Tags
update_tag_assignment	Tags
unassign_tag	Tags
get_tag_assignment_log	Tags
get_callback	Callbacks
create_callback	Callbacks
update_callback	Callbacks
search	Search
get_checklist_assignments	Checklists
assign_checklist	Checklists
unassign_checklist	Checklists
get_checklist_process	Checklists
check_checklist_item	Checklists
get_support_session	Support Sessions
create_support_session	Support Sessions
update_support_session	Support Sessions
update_support_list	Support Sessions
add_support_signature	Support Sessions
get_timer	Timers
create_timer	Timers
update_timer	Timers
delete_timer	Timers
get_timer_notes	Timers
update_timer_notes	Timers
delete_timer_notes	Timers
get_pc	PCs/Computers
create_pc	PCs/Computers
update_pc	PCs/Computers
delete_pc	PCs/Computers
get_peripheral	Peripherals
create_peripheral	Peripherals
update_peripheral	Peripherals
delete_peripheral	Peripherals
get_peripheral_types	Peripherals
create_peripheral_type	Peripherals
update_peripheral_type	Peripherals
delete_peripheral_type	Peripherals
install_builtin_peripheral	Peripherals
get_component	Components
create_component	Components
update_component	Components
delete_component	Components
get_component_types	Components
create_component_type	Components
update_component_type	Components
delete_component_type	Components
get_service	Services
create_service	Services
update_service	Services
delete_service	Services
get_ip_addresses	IP Addresses
create_ip_address	IP Addresses
update_ip_address	IP Addresses
delete_ip_address	IP Addresses
create_company	Companies
get_company_employees_list	Companies
get_company_category	Company Categories
create_company_category	Company Categories
update_company_category	Company Categories
delete_company_category	Company Categories
get_company_category_types	Company Categories
create_company_category_type	Company Categories
update_company_category_type	Company Categories
delete_company_category_type	Company Categories
get_document	Documents
create_document	Documents
upload_document	Documents
update_document	Documents
delete_document	Documents
get_webhook_rules	Webhooks
create_webhook_rule	Webhooks
update_webhook_rule	Webhooks
delete_webhook_rule	Webhooks
test_webhook	Webhooks
get_ticket_board	Ticket Board
get_ticket_board_project	Ticket Board
get_ticket_board_panel	Ticket Board
create_ticket_board_panel	Ticket Board
update_ticket_board_panel	Ticket Board
delete_ticket_board_panel	Ticket Board
get_project_registers	Ticket Board
get_panel_registers	Ticket Board
get_global_panels	Ticket Board
get_operating_system	Operating Systems
create_operating_system	Operating Systems
update_operating_system	Operating Systems
delete_operating_system	Operating Systems
get_manufacturer	Manufacturers
create_manufacturer	Manufacturers
update_manufacturer	Manufacturers
delete_manufacturer	Manufacturers
get_cpu	CPUs
create_cpu	CPUs
update_cpu	CPUs
delete_cpu	CPUs
get_hdd_type	HDD Types
create_hdd_type	HDD Types
update_hdd_type	HDD Types
delete_hdd_type	HDD Types
identify	Identification
get_email_account	Email Accounts
create_email_account	Email Accounts
update_email_account	Email Accounts
delete_email_account	Email Accounts
get_company_email_accounts	Email Accounts
get_email_account_types	Email Accounts
create_vacation_request	Vacation Requests
update_vacation_request	Vacation Requests
delete_vacation_request	Vacation Requests
update_vacation_request_list	Vacation Requests
get_vacation_days	Vacation Requests
set_vacation_days	Vacation Requests
get_vacation_additional_types	Vacation Requests
get_unseen_events	Activity Feed
mark_all_events_seen	Activity Feed
update_event	Activity Feed
get_domain	Domains
create_domain	Domains
update_domain	Domains
delete_domain	Domains
get_company_domains	Domains
login	Authentication
test_smtp	Mail Testing

Tool Categories

Category	Tools	Description
Tickets	6	Core ticket operations
Ticket Lists	10	Ticket filtering and views
Ticket Content	3	File uploads and screenshots
Ticket States	4	Ticket state management
Calls	8	Phone call management
Remote Support	11	Remote support sessions
Monitoring	7	System monitoring
ERP	15	ERP integration
Timestamp	15	Time tracking
Chats	10	Chat management
Offers	14	Offers and quotes
Tags	9	Tag management
Checklists	5	Checklist operations
Documents	5	Document management
Webhooks	5	Webhook configuration
Company	2	Company management
Employees	2	Employee operations
...	...	And 24 more categories

---

API Documentation

This MCP server implements the TANSS API v10.10.0.

Official TANSS API Documentation: 🔗 https://api-doc.tanss.de/#section/Documentation-of-the-TANSS-API.-Version:-10.10.0

The API documentation provides:

• Detailed endpoint specifications
• Request/response schemas
• Authentication requirements
• Parameter descriptions
• Example requests and responses

---

Architecture

Authentication Flow

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
│                    (Claude, etc.)                               │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ MCP Protocol
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                    TANSS MCP Server                             │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Tool Catalog (237 tools)                                │  │
│  │  - create_ticket                                         │  │
│  │  - get_my_tickets                                        │  │
│  │  - create_remote_support                                 │  │
│  │  - ...                                                   │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Token Manager                                           │  │
│  │  - Main API Token                                        │  │
│  │  - Role-specific Tokens (ERP, Phone, etc.)              │  │
│  │  - Automatic Bearer prefix handling                      │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ HTTP + Custom apiToken header
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                        TANSS API                                │
│                     (v10.10.0)                                  │
└─────────────────────────────────────────────────────────────────┘

Token Priority

When making API calls, the server uses this token priority:

1. Role-specific token (if configured for that endpoint category)
2. Main API token (fallback)

Example:

• ERP endpoints use erp_api_token if configured, otherwise api_token
• Ticket endpoints always use api_token

Custom Authentication Header

TANSS uses a custom authentication header instead of the standard Authorization header:

headers = {
    'apiToken': 'Bearer <token>',  # TANSS-specific
    'Content-Type': 'application/json'
}

The server handles this automatically.

---

Command-Line Options

python3 server.py --help

Options

Option	Values	Default	Description
--mode	stdio, sse	sse	Transport mode
--config	path	config.ini	Config file path
--host	hostname	127.0.0.1	SSE server host
--port	number	8000	SSE server port
--reload	flag	false	Auto-reload on changes
--log-level	debug, info, warning, error	info	Logging level

Examples

# stdio mode (default for Claude Desktop)
python3 server.py --mode stdio

# SSE mode for local development
python3 server.py --mode sse

# SSE mode for network access
python3 server.py --mode sse --host 0.0.0.0 --port 3001

# Development mode with auto-reload
python3 server.py --mode sse --reload --log-level debug

---

Security Notes

⚠️ Important Security Considerations:

• Use environment variables for tokens in production
• Rotate API tokens regularly
• Monitor token expiration dates
• Configure CORS properly for SSE mode in production
• Use HTTPS for production deployments

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

---

Support

Author: Sebastian Michel
Company: ProNet Systems GmbH
Website: https://www.pronet-systems.de

• Consult the official TANSS API Documentation

---

Made with ❤️ by ProNet Systems GmbH