Zammad MCP by usefulapi
Search and read Zammad tickets, customers and organizations; add notes, replies and ticket updates.
我该使用它吗
质量与安全性
基于对工具定义和协议合规性的自动分析。
上下文开销
这是每次将服务器的工具加载到模型上下文窗口时所消耗的大致 token 数。数值越高，可用于其他任务的注意力就越少。
安装
一键安装
将以下内容添加到你的 `claude_desktop_config.json` 文件中：
{
"mcpServers": {
"zammad": {
"url": "https://zammad.usefulapi.io/mcp"
}
}
}远程端点
https://zammad.usefulapi.io/mcpstreamable-http它能做什么
工具清单
工具（19）
🟢zammad_get_me
The Zammad user this access token belongs to: id, name, e-mail, roles and groups. Use it to confirm the connection and the token's permissions. GET /api/v1/users/me.
输入模式
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_search_tickets(query, sort_by, order_by, page, per_page)
Search tickets with Zammad's query syntax. With Elasticsearch on the instance you can use fields, e.g. `state.name:open AND group.name:Sales`, `customer.email:"[email protected]"`, `title:invoice`, `number:20001`; a plain word searches ticket text. Replies carry ids plus names (group, state, priority, owner, customer). GET /api/v1/tickets/search?expand=true.
输入模式
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Search query."
},
"sort_by": {
"description": "Field to sort by, e.g. updated_at or created_at.",
"type": "string",
"pattern": "^[a-z_.]{1,60}$"
},
"order_by": {
"description": "Sort direction (default: relevance).",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"query"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_tickets(page, per_page)
List the tickets the token's user can see (an agent sees the tickets of their groups; a customer only their own). For anything targeted use zammad_search_tickets. GET /api/v1/tickets?expand=true.
输入模式
{
"type": "object",
"properties": {
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_get_ticket(ticket_id)
One ticket by its numeric id (not the ticket number): title, group, state, priority, owner, customer, organization, dates, escalation and article count. GET /api/v1/tickets/{id}?expand=true.
输入模式
{
"type": "object",
"properties": {
"ticket_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad ticket id (the number in the ticket URL, not the 5-digit ticket number)."
}
},
"required": [
"ticket_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_ticket_articles(ticket_id)
All articles (messages, internal notes, e-mails, phone notes) of one ticket in order, with sender, type, internal flag, from/to/cc, subject, body and attachment names (attachments are not downloaded). Long bodies are cut at 6000 characters; use zammad_get_ticket_article for the full text. GET /api/v1/ticket_articles/by_ticket/{ticket_id}.
输入模式
{
"type": "object",
"properties": {
"ticket_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad ticket id."
}
},
"required": [
"ticket_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_get_ticket_article(article_id)
One article by its id with its full body, headers and attachment names. GET /api/v1/ticket_articles/{id}.
输入模式
{
"type": "object",
"properties": {
"article_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad article id (from zammad_list_ticket_articles)."
}
},
"required": [
"article_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_ticket_tags(ticket_id)
The tags on one ticket. GET /api/v1/tags?object=Ticket&o_id={ticket_id}. Needs an agent token.
输入模式
{
"type": "object",
"properties": {
"ticket_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad ticket id."
}
},
"required": [
"ticket_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_ticket_states
The ticket states of the instance (new, open, pending reminder, pending close, closed, ...) with ids and whether they are active. Use the names in zammad_update_ticket. GET /api/v1/ticket_states.
输入模式
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_ticket_priorities
The ticket priorities of the instance (e.g. '1 low', '2 normal', '3 high') with ids. Use the names in zammad_update_ticket. GET /api/v1/ticket_priorities.
输入模式
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_groups(page, per_page)
The ticket groups (queues) of the instance, with ids, names and agent ids. Zammad requires the admin.group permission for this list; with an agent-only token it returns an authorization error. GET /api/v1/groups.
输入模式
{
"type": "object",
"properties": {
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_search_users(query, page, per_page)
Search customers and agents by name, e-mail, login, phone or organization. Returns profile fields (no credentials). Needs an agent token. GET /api/v1/users/search?expand=true.
输入模式
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "Search text, e.g. an e-mail address or a name."
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"query"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_get_user(user_id)
One user (customer or agent) by id: name, e-mail, phone, organization, roles, VIP flag and notes. No credentials. GET /api/v1/users/{id}?expand=true.
输入模式
{
"type": "object",
"properties": {
"user_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad user id."
}
},
"required": [
"user_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_search_organizations(query, page, per_page)
Search customer organizations by name or domain. Needs an agent token. GET /api/v1/organizations/search.
输入模式
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "Search text, e.g. an organization name."
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"query"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_list_organizations(page, per_page)
List customer organizations with domain, VIP flag and member ids. Needs an agent token. GET /api/v1/organizations.
输入模式
{
"type": "object",
"properties": {
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢zammad_get_organization(organization_id)
One organization by id: name, domain, notes, VIP flag, member ids. GET /api/v1/organizations/{id}.
输入模式
{
"type": "object",
"properties": {
"organization_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad organization id."
}
},
"required": [
"organization_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴zammad_add_internal_note(ticket_id, body, subject)
WRITE: add an INTERNAL note (visible to agents only, never e-mailed to the customer) to ONE ticket. Needs an agent's token (a customer's token is refused, because Zammad would make the note public). The ticket's other data is not changed. POST /api/v1/ticket_articles with type=note, internal=true.
输入模式
{
"type": "object",
"properties": {
"ticket_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad ticket id."
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "Note text (plain text)."
},
"subject": {
"description": "Optional note subject (one line).",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"ticket_id",
"body"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴zammad_reply_to_ticket(ticket_id, body, to, subject)
WRITE: send a customer-visible reply on ONE ticket. THIS E-MAILS A REAL PERSON: the reply is delivered by e-mail to exactly ONE recipient and cannot be recalled. By default the recipient is the ticket's customer (looked up from the ticket); `to` may name one other single address. No cc, no bulk, no attachments. Needs an agent's token (a customer's token is refused). For an internal remark use zammad_add_internal_note. GET /api/v1/tickets/{id}, then POST /api/v1/ticket_articles with type=email, internal=false.
输入模式
{
"type": "object",
"properties": {
"ticket_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad ticket id."
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "Reply text (plain text)."
},
"to": {
"description": "Optional: ONE recipient e-mail address. Default: the ticket customer's address.",
"type": "string",
"maxLength": 254,
"pattern": "^[^\\s,;<>\"'()[\\]\\\\@]+@[^\\s,;<>\"'()[\\]\\\\@]+\\.[^\\s,;<>\"'()[\\]\\\\@]+$"
},
"subject": {
"description": "Optional subject (one line). Default: 'Re: <ticket title>'.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"ticket_id",
"body"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴zammad_update_ticket(ticket_id, state, priority, owner_id, group, ...)
WRITE: change fields of ONE ticket: state, priority, owner (agent), group and/or title. Use names from zammad_list_ticket_states / zammad_list_ticket_priorities / zammad_list_groups. Pending states need `pending_time`. Never deletes, removes or merges (those states are refused). The instance's own triggers still run, so closing or reassigning a ticket can send the customer or agent a notification e-mail. PUT /api/v1/tickets/{id}.
输入模式
{
"type": "object",
"properties": {
"ticket_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Zammad ticket id."
},
"state": {
"description": "State name, e.g. open, closed, 'pending reminder'.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"priority": {
"description": "Priority name, e.g. '3 high'.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"owner_id": {
"description": "User id of the agent who should own the ticket. Id 1 is Zammad's 'no owner' placeholder.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"group": {
"description": "Group name, e.g. Sales (subgroups as Sales::Europe).",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"title": {
"description": "New ticket title.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"pending_time": {
"description": "Required for the pending states: when the ticket reminds or closes, ISO 8601 with a timezone.",
"type": "string"
}
},
"required": [
"ticket_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴zammad_create_ticket(title, group, customer, customer_id, body, ...)
WRITE: create ONE new ticket for an EXISTING customer (by e-mail address or user id) in a group, with a first article recorded as written by the customer (type note or phone). It does not send an e-mail by itself, but the instance's triggers may (for example an automatic confirmation to the customer). It never creates new users. POST /api/v1/tickets.
输入模式
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Ticket title."
},
"group": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Group name the ticket goes to, e.g. Users or Sales."
},
"customer": {
"description": "E-mail address of an existing customer. Give this or customer_id.",
"type": "string",
"maxLength": 254,
"pattern": "^[^\\s,;<>\"'()[\\]\\\\@]+@[^\\s,;<>\"'()[\\]\\\\@]+\\.[^\\s,;<>\"'()[\\]\\\\@]+$"
},
"customer_id": {
"description": "User id of an existing customer. Give this or customer.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "First message of the ticket (plain text)."
},
"subject": {
"description": "Subject of the first article (default: the title).",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"article_type": {
"description": "Type of the first article: note (default) or phone.",
"type": "string",
"enum": [
"note",
"phone"
]
},
"state": {
"description": "Initial state name (default: new).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"priority": {
"description": "Initial priority name (default: 2 normal).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"owner_id": {
"description": "User id of the agent who should own the ticket.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"title",
"group",
"body"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}社区
证据