Search

Full-text search, one action per kind of result: code, merge requests, issues, commits, milestones, notes, projects, snippets, users and wiki pages. Each searches a project or a group when given one, and the whole instance otherwise. search_type asks for a search backend, basic, advanced or zoekt, and GitLab refuses one the instance has not enabled. Every action only reads.

Sample questions

• “Search the code of group platform for parseConfig”
• “Find merge requests that mention the login bug”
• “Which issues mention timeout in project 42?”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as search.code, 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_search with action set to the action’s name, such as code, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_search_code, 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: 10 of 10, the ones a deployment in read-only mode keeps.

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.

Action	Individual
search.code	gitlab_search_code
search.commits	gitlab_search_commits
search.issues	gitlab_search_issues
search.merge_requests	gitlab_search_merge_requests
search.milestones	gitlab_search_milestones
search.notes	gitlab_search_notes
search.projects	gitlab_search_projects
search.snippets	gitlab_search_snippets
search.users	gitlab_search_users
search.wiki	gitlab_search_wiki

search.code

Search code blobs across global, group, or project scope. Returns: matching blobs with file path, basename, ref, starting line, the surrounding snippet, project ID, and pagination metadata. See also: search.projects, repository.file_get, repository.tree.

• Meta-tool: gitlab_search, action code
• Individual tool: gitlab_search_code
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query text (param ‘query’ not ‘search’)
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
ref	string	no	Branch or tag name to search in (default: default branch)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.commits

Search commit messages across global, group, or project scope. Returns: matching commits with short and full SHA, title, message, author, and committed date plus pagination metadata. See also: search.code, repository.commit_get, repository.file_history.

• Meta-tool: gitlab_search, action commits
• Individual tool: gitlab_search_commits
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query string
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.issues

Search issues across global, group, or project scope. Returns: matching issues with title, state, labels, assignees, author, and web URL plus pagination metadata. See also: search.merge_requests, issue.list, issue.get.

• Meta-tool: gitlab_search, action issues
• Individual tool: gitlab_search_issues
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query text (param ‘query’ not ‘search’)
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.merge_requests

Search merge requests across global, group, or project scope. Returns: matching merge requests with title, state, author, source and target branches, and web URL plus pagination metadata. See also: search.issues, merge_request.list, merge_request.get.

• Meta-tool: gitlab_search, action merge_requests
• Individual tool: gitlab_search_merge_requests
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query text (param ‘query’ not ‘search’)
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.milestones

Search milestones across global, group, or project scope. Returns: matching milestones with title, description, state, start and due dates, and web URL plus pagination metadata. See also: project.milestone_list, project.milestone_get, search.issues.

• Meta-tool: gitlab_search, action milestones
• Individual tool: gitlab_search_milestones
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query string
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.notes

Search note bodies within one project. Returns: matching notes with body, author, noteable type and ID, system flag, and timestamps plus pagination metadata. See also: search.issues, search.merge_requests, issue.note_list.

• Meta-tool: gitlab_search, action notes
• Individual tool: gitlab_search_notes
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string	yes	Project ID or URL-encoded path
query	string	yes	Search query string
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.projects

Search projects globally or within a group by name, path, or description. Returns: matching projects with namespace, visibility, default branch, and web URL plus pagination metadata. See also: project.get, project.list, search.code.

• Meta-tool: gitlab_search, action projects
• Individual tool: gitlab_search_projects
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query string
group_id	string	no	Group ID or URL-encoded path. Omit for a global search
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.snippets

Search snippet titles globally. Returns: matching snippets with title, file name, description, visibility, author, project ID, web and raw URLs, and timestamps plus pagination metadata. See also: search.code, search.projects.

• Meta-tool: gitlab_search, action snippets
• Individual tool: gitlab_search_snippets
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query string
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.users

Search users across global, group, or project scope. Returns: matching users with ID, username, name, state, avatar URL, and web URL plus pagination metadata. See also: user.get, user.list, project.members.

• Meta-tool: gitlab_search, action users
• Individual tool: gitlab_search_users
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query string
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.

search.wiki

Search wiki blobs across global, group, or project scope. Returns: matching wiki pages with slug, title, content snippet, and format plus pagination metadata. See also: search.code, wiki.list, wiki.get.

• Meta-tool: gitlab_search, action wiki
• Individual tool: gitlab_search_wiki
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	string	yes	Search query string
group_id	string	no	Group ID or URL-encoded path (optional)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
project_id	string	no	Project ID or URL-encoded path (optional)
search_type	string (basic, advanced, zoekt)	no	Search backend to request. Use ‘basic’ for GitLab’s default search, ‘advanced’ for Elasticsearch/OpenSearch-backed search, or ‘zoekt’ for Zoekt-based search. The requested backend must be enabled on the GitLab instance.