pronet-systems/tanss-mcp-server

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

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