Otobo MCP

mcp耳罩

A. 模型上下文协议（MCP） 服务器 奥托博 --开源ITSM和帮助台系统。该服务器使AI助手能够通过通用接口REST API在Otobo实例中搜索、创建、更新和管理票证。

特性

• 搜索门票 按队列、状态、优先级、客户、标题、日期范围等
• 获取门票详细信息 包括完整的通信历史和动态字段
• 创建工单 初始文章
• 更新门票 --更改状态、队列、优先级、所有者、添加文章
• 关闭门票 带有可选的结束语
• 添加内部注释 到票
• 查看门票历史记录 --变更的完整审计跟踪
• 列出队列、状态和优先级 从您的Otobo实例

先决条件

• Node.js 18岁或以后
• 一 Otobo实例 使用已配置的通用接口web服务（请参见 Otobo设置)
• 一 代理账户 具有API访问权限

安装

npm install -g mcp-otobo

或者直接使用npx运行：

npx mcp-otobo

或者克隆并从源代码构建：

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

配置

服务器是通过环境变量配置的：

复制 .env.example 到 .env 并填写您的值：

cp .env.example .env

可用工具

核心票务运营

历史

元数据

便利

集成示例

克劳德桌面

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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"
      }
    }
  }
}

或者，如果从源代码安装：

{
  "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"
      }
    }
  }
}

克劳德代码

添加到您的项目 .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"
      }
    }
  }
}

或者通过CLI添加环境变量：

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

光标

添加到光标MCP设置(.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 MCP配置(~/.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（通过MCP桥）

ChatGPT本身不支持MCP。然而，存在第三方MCP-to-OpenAI桥接工具，可以将任何MCP服务器公开为与OpenAI兼容的函数调用API。搜索“MCP OpenAI网桥”或“MCP代理”以获取当前选项。

Codex CLI

在Codex配置中设置环境变量并配置MCP：

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"

或添加到您的 ~/.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 MCP设置文件(~/.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"
      }
    }
  }
}

通用MCP客户端

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

要使用此MCP服务器，您的Otobo实例需要正确配置 通用接口 web服务。

步骤1：创建Web服务

1. 以管理员身份登录Otobo
2. 导航至 管理员→ 通用接口→ 网络服务
3. 点击 添加Web服务
4. 设置：

- 名字: GenericTicketConnectorREST （或您的首选名称--必须匹配 OTOBO_WEBSERVICE) - 网络传输: HTTP::REST

步骤2：添加操作

将以下四个操作添加到您的web服务中。对于每一个：

1. 点击 添加操作
2. 设置 名字 （例如。 TicketCreate)
3. 选择 操作后端:

1. 将映射设置保留为默认值
2. 点击 保存

步骤3：配置传输和路由映射

1. 回到web服务概述，转到 网络传输→ 配置
2. 集 最大消息长度: 10000000 （对于大额门票，价格更高）
3. 配置 路线图 对于每个操作：

1. 保存

步骤4：创建API代理

安全说明： 一旦REST web服务处于活动状态， 任何有效的代理帐户 无法将web服务本身限制为特定用户。访问控制完全通过组和队列权限来处理。强烈建议创建具有最低权限的专用API代理。

1. 导航至 管理员→ 代理
2. 为API访问创建专用代理帐户（例如。 api-user)
3. 创建一个专门的小组（例如。 api-access)under 管理员→ 群组
4. 在...之下 管理员→ 代理↔ 群组，仅将API代理分配到此组
5. 在...之下 管理员→ 队列↔ 群组，仅授予对API应访问的队列的访问权限
6. 使用此代理的凭据 OTOBO_USERNAME 和 OTOBO_PASSWORD

步骤5：验证

使用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"}'

您应该得到一个包含票证ID的JSON响应。

故障排除

“缺少必需的环境变量”

确保设置了所有必需的环境变量。检查您的MCP客户端配置是否通过 env 正确堵塞。

“Otobo API错误（HTTP 403）”

您的代理帐户可能缺少必要的权限。检查：

• 该代理在Otobo中存在且有效
• 代理对您尝试访问的队列具有组权限
• web服务处于活动状态（未停用）

“Otobo API错误（HTTP 404）”

找不到web服务终结点。验证：

• web服务名称匹配 OTOBO_WEBSERVICE
• 操作配置了正确的路由映射
• Otobo URL正确且可访问

“Otobo API错误（HTTP 500）”

Otobo中的内部服务器错误。检查：

• Otobo系统日志(/opt/otobo/var/log/ 或您的日志目录）
• 请求负载有效（队列、状态、优先级等必填字段）
• 创建工单时系统中存在客户用户

连接问题

• 确保您的Otobo实例可以从运行MCP服务器的计算机访问
• 检查防火墙、VPN要求或SSL证书问题
• 对于自签名或内部SSL证书，请设置 OTOBO_UNSAFE_SSL=true 在您的环境配置中

list_queues/list_states/list_priorities的“未找到票证”

这些元数据工具从现有票证中发现值。如果您的系统还没有票，它们将返回默认值。首先创建测试票，或使用已知的默认值：

• 队列: Raw, Junk, Misc, Postmaster （取决于您的设置）
• 州: new, open, pending reminder, closed successful, closed unsuccessful
• 优先事项: 1 very low, 2 low, 3 normal, 4 high, 5 very high

许可证

麻省理工学院