Custom emoji

A group’s custom emoji are images it adds to the emoji its projects can react with and write in Markdown. These actions list, add and delete them. Reacting to an issue, a merge request or a snippet with an emoji is not one of them: those are actions of the issue, merge request and snippet groups. Deleting an emoji leaves the reactions that used it in place, shown as its :name:.

Sample questions

• “List the custom emoji of group platform”
• “Add a party_parrot emoji to group platform”
• “Delete the outdated custom emoji”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as custom_emoji.create, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_custom_emoji with action set to the action’s name, such as create, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_create_custom_emoji, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 1 of 3, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 1 of the 3.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.4.1 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action	Individual
custom_emoji.create	gitlab_create_custom_emoji
custom_emoji.delete	gitlab_delete_custom_emoji
custom_emoji.list	gitlab_list_custom_emoji

custom_emoji.create

Create group-level custom emoji using GraphQL-backed routes.

• Meta-tool: gitlab_custom_emoji, action create
• Individual tool: gitlab_create_custom_emoji
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Not reachable at this release: GitLab declares no fine-grained permission for CustomEmoji in the answer, so the write commits and its answer is lost (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
group_path	string	yes	Group full path (e.g. my-group)
name	string	yes	Emoji name without colons (e.g. party_parrot)
url	string	yes	URL to the emoji image (PNG or GIF recommended)

custom_emoji.delete

Delete group-level custom emoji using GraphQL-backed routes.

• Meta-tool: gitlab_custom_emoji, action delete
• Individual tool: gitlab_delete_custom_emoji
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Not reachable at this release: GitLab declares no fine-grained permission for CustomEmoji in the answer, so the write commits and its answer is lost (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
id	string	yes	Custom emoji GID (e.g. gid://gitlab/CustomEmoji/1)

custom_emoji.list

List group-level custom emoji using GraphQL-backed routes. A subgroup is listed with its own emoji only, as GitLab defaults. Set include_ancestor_groups to true to add the emoji of its ancestor groups, which it can use as well.

• Meta-tool: gitlab_custom_emoji, action list
• Individual tool: gitlab_list_custom_emoji
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Not reachable at this release: GitLab declares no fine-grained permission for CustomEmoji, which the answer is made of (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
group_path	string	yes	Group full path (e.g. my-group)
after	string	no	Cursor for forward pagination (from previous response end_cursor)
before	string	no	Cursor for backward pagination (from previous response start_cursor). The page size comes from last, or from first when last is omitted
first	integer	no	Number of items to return (default 20, max 100)
include_ancestor_groups	boolean	no	Also list the custom emoji of every ancestor group, which a subgroup can use as well. Default false, as GitLab defaults: a subgroup is then listed with its own emoji only
last	integer	no	Number of items to return from the end of the range (backward pagination). Cannot be combined with first