execute_custom_query

Execute custom GraphQL queries to filter GitLab issues, merge requests, and other data by assignee, author, labels, or other criteria when standard search tools return no results.

Instructions

Execute custom GraphQL queries for complex filtering (e.g., issues with assigneeUsernames: ["user"], labelName: ["bug"]). Use this for structured filtering by assignee/author/labels when search tools return 0 results. Use pagination and limit complexity to avoid timeouts.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	GraphQL query string. Example: query { issues(assigneeUsernames: ["cdhanlon"], state: opened, first: 50) { nodes { iid title webUrl } } }
`variables`	No	Variables for the GraphQL query
`requiresWrite`	No	Set to true if this is a mutation that requires write permissions
`userCredentials`	No	Your GitLab credentials (optional - uses shared token if not provided)

Implementation Reference

src/tools.ts:256-262 (handler)

Handler function that executes the custom GraphQL query. It validates user credentials, checks if write operations require authentication, and calls the client.query() method with the provided query string, variables, credentials, and write flag.

handler: async (input, client, userConfig) => {
  const credentials = input.userCredentials ? validateUserConfig(input.userCredentials) : userConfig;
  if (input.requiresWrite && !credentials) {
    throw new Error('User authentication is required for write operations. Please provide your GitLab credentials.');
  }
  return await client.query(input.query, input.variables, credentials, input.requiresWrite);
},

src/tools.ts:240-263 (schema)

Complete tool definition including input schema with user authentication support. Defines the tool name 'execute_custom_query', description, input schema (query string, optional variables, requiresWrite flag), and handler.

const executeCustomQueryTool: Tool = {
  name: 'execute_custom_query',
  title: 'Custom GraphQL Query',
  description: 'Execute custom GraphQL queries for complex filtering (e.g., issues with assigneeUsernames: ["user"], labelName: ["bug"]). Use this for structured filtering by assignee/author/labels when search tools return 0 results. Use pagination and limit complexity to avoid timeouts.',
  requiresAuth: false,
  requiresWrite: false,
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,
  },
  inputSchema: withUserAuth(z.object({
    query: z.string().describe('GraphQL query string. Example: query { issues(assigneeUsernames: ["cdhanlon"], state: opened, first: 50) { nodes { iid title webUrl } } }'),
    variables: z.record(z.any()).optional().describe('Variables for the GraphQL query'),
    requiresWrite: z.boolean().default(false).describe('Set to true if this is a mutation that requires write permissions'),
  })),
  handler: async (input, client, userConfig) => {
    const credentials = input.userCredentials ? validateUserConfig(input.userCredentials) : userConfig;
    if (input.requiresWrite && !credentials) {
      throw new Error('User authentication is required for write operations. Please provide your GitLab credentials.');
    }
    return await client.query(input.query, input.variables, credentials, input.requiresWrite);
  },
};

src/tools.ts:1294-1310 (registration)

The tool is registered in the readOnlyTools export array, which makes it available as a read-only tool in the MCP server.

export const readOnlyTools: Tool[] = [
  getProjectTool,
  getIssuesTool,
  getMergeRequestsTool,
  executeCustomQueryTool,
  getAvailableQueriesTools,
  getMergeRequestPipelinesTool,
  getPipelineJobsTool,
  getMergeRequestDiffsTool,
  getMergeRequestCommitsTool,
  getNotesTool,
  listMilestonesTool,
  listIterationsTool,
  getTimeTrackingTool,
  getMergeRequestReviewersTool,
  getProjectStatisticsTool,
];

src/tools.ts:1339-1349 (registration)

The tool is also included in the main tools export array that aggregates all tool categories (readOnlyTools, userAuthTools, writeTools, and searchTools).

export const tools: Tool[] = [
  ...readOnlyTools,
  ...userAuthTools,
  ...writeTools,
  updateIssueTool,
  updateMergeRequestTool,
  resolvePathTool,
  getGroupProjectsTool,
  getTypeFieldsTool,
  ...searchTools,
];

src/gitlab-client.ts:306-312 (helper)

The client.query method that actually executes GraphQL queries with retry logic. It gets the appropriate GraphQL client (user-specific or shared) and executes the query with exponential backoff retry for reliability.

async query<T = any>(query: string, variables?: any, userConfig?: UserConfig, requiresWrite = false): Promise<T> {
  const client = this.getClient(userConfig, requiresWrite);
  return this.executeWithRetry(
    () => client.request<T>(query, variables),
    'GraphQL query'
  );
}

GitLab MCP Server