mcp-otobo

A Model Context Protocol (MCP) server for Otobo — the open-source ITSM and helpdesk system. This server enables AI assistants to search, create, update, and manage tickets in your Otobo instance through the Generic Interface REST API.

Features

• Search tickets by queue, state, priority, customer, title, date ranges, and more
• Get ticket details including full communication history and dynamic fields
• Create tickets with initial articles
• Update tickets — change state, queue, priority, owner, add articles
• Close tickets with optional closing notes
• Add internal notes to tickets
• View ticket history — full audit trail of changes
• List queues, states, and priorities from your Otobo instance

Prerequisites

• Node.js 18 or later
• An Otobo instance with a configured Generic Interface web service (see Otobo Setup)
• An agent account with API access permissions

Installation

npm install -g mcp-otobo

Or run directly with npx:

npx mcp-otobo

Or clone and build from source:

git clone https://github.com/domnussbaum/otobo-mcp.git
cd mcp-otobo
npm install
npm run build

Configuration

The server is configured via environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | OTOBO_BASE_URL | Yes | — | Your Otobo instance URL (e.g. https://otobo.example.com) | | OTOBO_USERNAME | Yes | — | Agent username for API access | | OTOBO_PASSWORD | Yes | — | Agent password | | OTOBO_WEBSERVICE | No | GenericTicketConnectorREST | Web service name configured in Otobo | | OTOBO_UNSAFE_SSL | No | false | Set to true to allow self-signed/internal SSL certificates |

Copy .env.example to .env and fill in your values:

cp .env.example .env

Available Tools

Core Ticket Operations

| Tool | Description | |---|---| | search_tickets | Search tickets by queue, state, priority, customer, title, ticket number, date ranges | | get_ticket | Get full ticket details with articles and dynamic fields | | create_ticket | Create a new ticket with first article | | update_ticket | Update ticket fields and optionally add an article |

History

| Tool | Description | |---|---| | get_ticket_history | Get the full change history of a ticket |

Metadata

| Tool | Description | |---|---| | list_queues | List available queues in the system | | list_states | List available ticket states | | list_priorities | List available ticket priorities |

Convenience

| Tool | Description | |---|---| | close_ticket | Close a ticket with an optional note | | add_note | Add an internal note to a ticket |

Integration Examples

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "otobo": {
      "command": "npx",
      "args": ["-y", "mcp-otobo"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password",
        "OTOBO_WEBSERVICE": "GenericTicketConnectorREST"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "otobo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-otobo/build/index.js"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "otobo": {
      "command": "npx",
      "args": ["-y", "mcp-otobo"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password",
        "OTOBO_WEBSERVICE": "GenericTicketConnectorREST"
      }
    }
  }
}

Or add it via the CLI with environment variables:

claude mcp add otobo \
  -e OTOBO_BASE_URL=https://otobo.example.com \
  -e OTOBO_USERNAME=your-agent-user \
  -e 'OTOBO_PASSWORD=your-agent-password' \
  -e OTOBO_WEBSERVICE=GenericTicketConnectorREST \
  -- npx -y mcp-otobo

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "otobo": {
      "command": "npx",
      "args": ["-y", "mcp-otobo"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password",
        "OTOBO_WEBSERVICE": "GenericTicketConnectorREST"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "otobo": {
      "command": "npx",
      "args": ["-y", "mcp-otobo"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password",
        "OTOBO_WEBSERVICE": "GenericTicketConnectorREST"
      }
    }
  }
}

ChatGPT / OpenAI (via MCP Bridge)

ChatGPT does not natively support MCP. However, third-party MCP-to-OpenAI bridge tools exist that can expose any MCP server as an OpenAI-compatible function-calling API. Search for "MCP OpenAI bridge" or "MCP proxy" for current options.

Codex CLI

Set up environment variables and configure MCP in your Codex configuration:

export OTOBO_BASE_URL=https://otobo.example.com
export OTOBO_USERNAME=your-agent-user
export OTOBO_PASSWORD='your-agent-password'

codex --full-auto "Search for open tickets"

Or add to your ~/.codex/config.json:

{
  "mcpServers": {
    "otobo": {
      "command": "npx",
      "args": ["-y", "mcp-otobo"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password",
        "OTOBO_WEBSERVICE": "GenericTicketConnectorREST"
      }
    }
  }
}

Gemini CLI

Add to your Gemini CLI MCP settings file (~/.gemini/settings.json):

{
  "mcpServers": {
    "otobo": {
      "command": "npx",
      "args": ["-y", "mcp-otobo"],
      "env": {
        "OTOBO_BASE_URL": "https://otobo.example.com",
        "OTOBO_USERNAME": "your-agent-user",
        "OTOBO_PASSWORD": "your-agent-password",
        "OTOBO_WEBSERVICE": "GenericTicketConnectorREST"
      }
    }
  }
}

Generic MCP Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "mcp-otobo"],
  env: {
    OTOBO_BASE_URL: "https://otobo.example.com",
    OTOBO_USERNAME: "your-agent-user",
    OTOBO_PASSWORD: "your-agent-password",
    OTOBO_WEBSERVICE: "GenericTicketConnectorREST",
  },
});

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Search for open tickets
const result = await client.callTool("search_tickets", {
  states: ["open", "new"],
  limit: 10,
});
console.log(result);

Otobo Setup

To use this MCP server, your Otobo instance needs a properly configured Generic Interface web service.

Step 1: Create a Web Service

1. Log in to Otobo as an admin
2. Navigate to Admin → Generic Interface → Web Services
3. Click Add Web Service
4. Set:
   • Name: GenericTicketConnectorREST (or your preferred name — must match OTOBO_WEBSERVICE)
   • Network Transport: HTTP::REST

Step 2: Add Operations

Add the following four operations to your web service. For each one:

1. Click Add Operation
2. Set the Name (e.g. TicketCreate)
3. Select the Operation-Backend:

| Name | Operation-Backend | |---|---| | TicketCreate | Ticket::TicketCreate | | TicketGet | Ticket::TicketGet | | TicketSearch | Ticket::TicketSearch | | TicketUpdate | Ticket::TicketUpdate |

4. Leave mapping settings at their defaults
5. Click Save

Step 3: Configure Transport & Route Mapping

1. Back on the web service overview, go to Network Transport → Configure
2. Set Maximum message length: 10000000 (or higher for large tickets)
3. Configure the Route mapping for each operation:

| Operation | Route | Request Method | |---|---|---| | TicketCreate | /TicketCreate | POST | | TicketGet | /TicketGet | POST | | TicketSearch | /TicketSearch | POST | | TicketUpdate | /TicketUpdate | POST |

4. Save

Step 4: Create an API Agent

Security note: Once a REST web service is active, any valid agent account can authenticate against it. There is no way to restrict the web service itself to specific users. Access control is handled entirely through group and queue permissions. It is strongly recommended to create a dedicated API agent with minimal permissions.

1. Navigate to Admin → Agents
2. Create a dedicated agent account for API access (e.g. api-user)
3. Create a dedicated group (e.g. api-access) under Admin → Groups
4. Under Admin → Agents ↔ Groups, assign only the API agent to this group
5. Under Admin → Queues ↔ Groups, grant access only to the queues the API should reach
6. Use this agent's credentials for OTOBO_USERNAME and OTOBO_PASSWORD

Step 5: Verify

Test your setup with curl:

curl -X POST \
  "https://otobo.example.com/otobo/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/TicketSearch" \
  -H "Content-Type: application/json" \
  -d '{"UserLogin":"your-agent","Password":"your-password"}'

You should get a JSON response with ticket IDs.

Troubleshooting

"Missing required environment variable"

Make sure all required environment variables are set. Check that your MCP client configuration passes the env block correctly.

"Otobo API error (HTTP 403)"

Your agent account may lack the necessary permissions. Check:

• The agent exists and is valid in Otobo
• The agent has group permissions for the queues you're trying to access
• The web service is active (not deactivated)

"Otobo API error (HTTP 404)"

The web service endpoint is not found. Verify:

• The web service name matches OTOBO_WEBSERVICE
• The operations are configured with correct route mappings
• The Otobo URL is correct and accessible

"Otobo API error (HTTP 500)"

An internal server error in Otobo. Check:

• Otobo system logs (/opt/otobo/var/log/ or your log directory)
• The request payload is valid (required fields like Queue, State, Priority)
• Customer user exists in the system when creating tickets

Connection Issues

• Ensure your Otobo instance is reachable from the machine running the MCP server
• Check for firewalls, VPN requirements, or SSL certificate issues
• For self-signed or internal SSL certificates, set OTOBO_UNSAFE_SSL=true in your environment configuration

"No tickets found" for list_queues/list_states/list_priorities

These metadata tools discover values from existing tickets. If your system has no tickets yet, they return default values. Create a test ticket first, or use the known defaults:

• Queues: Raw, Junk, Misc, Postmaster (depends on your setup)
• States: new, open, pending reminder, closed successful, closed unsuccessful
• Priorities: 1 very low, 2 low, 3 normal, 4 high, 5 very high

License

MIT