Jira MCP Server

Instructions

Implementation Reference

• src/index.ts:307-342 (handler)

  MCP tool handler function for search_issues that validates JQL input, calls the underlying searchIssues helper, limits results, formats output with assignee display names, and handles errors.

  async ({ jql, maxResults }) => {
    try {
      if (!jql || !jql.trim()) {
        throw new Error('jql is required');
      }
  
      const issues = await searchIssues(jql, ['summary', 'status', 'priority', 'assignee', 'updated']);
      
      // Apply maxResults limit (default 50, max 100)
      const limit = Math.min(maxResults || 50, 100);
      const limitedIssues = issues.slice(0, limit);
      
      // Map to include assignee display name
      const mappedIssues = limitedIssues.map(issue => ({
        key: issue.key,
        summary: issue.summary,
        status: issue.status,
        priority: issue.priority,
        assignee: issue.assignee,
        updated: issue.updated,
      }));
  
      const output = { issues: mappedIssues, total: issues.length };
      return {
        content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
        structuredContent: output,
      };
    } catch (error) {
      const errOutput = formatError(error);
      return {
        content: [{ type: 'text', text: JSON.stringify(errOutput, null, 2) }],
        structuredContent: errOutput,
        isError: true,
      };
    }
  }

• src/index.ts:283-306 (schema)

  Input and output schemas using Zod for the search_issues tool, defining JQL query input and structured issues output.

  {
    title: 'Search Issues',
    description: 'Search for issues using JQL (Jira Query Language). Use this to find issues by parent/epic, assignee, status, labels, or any other criteria. Example JQL: "parent=TSSE-206", "assignee=currentuser() AND status=\"In Progress\"", "labels=Dec15-19"',
    inputSchema: {
      jql: z.string().describe('JQL query string (e.g., "parent=EPIC-123", "project=TSSE AND status=\"To Do\"")'),
      maxResults: z.number().optional().describe('Maximum number of results to return (default: 50, max: 100)'),
    },
    outputSchema: {
      issues: z.array(z.object({
        key: z.string(),
        summary: z.string(),
        status: z.string(),
        priority: z.string(),
        assignee: z.string().optional(),
        updated: z.string(),
      })).optional(),
      total: z.number().optional(),
      error: z.object({
        message: z.string(),
        statusCode: z.number().optional(),
        details: z.unknown().optional(),
      }).optional(),
    },
  },

• src/index.ts:281-342 (registration)

  Full registration of the search_issues tool with MCP server, including name, schema, title, description, and handler function.

  server.registerTool(
    'search_issues',
    {
      title: 'Search Issues',
      description: 'Search for issues using JQL (Jira Query Language). Use this to find issues by parent/epic, assignee, status, labels, or any other criteria. Example JQL: "parent=TSSE-206", "assignee=currentuser() AND status=\"In Progress\"", "labels=Dec15-19"',
      inputSchema: {
        jql: z.string().describe('JQL query string (e.g., "parent=EPIC-123", "project=TSSE AND status=\"To Do\"")'),
        maxResults: z.number().optional().describe('Maximum number of results to return (default: 50, max: 100)'),
      },
      outputSchema: {
        issues: z.array(z.object({
          key: z.string(),
          summary: z.string(),
          status: z.string(),
          priority: z.string(),
          assignee: z.string().optional(),
          updated: z.string(),
        })).optional(),
        total: z.number().optional(),
        error: z.object({
          message: z.string(),
          statusCode: z.number().optional(),
          details: z.unknown().optional(),
        }).optional(),
      },
    },
    async ({ jql, maxResults }) => {
      try {
        if (!jql || !jql.trim()) {
          throw new Error('jql is required');
        }
  
        const issues = await searchIssues(jql, ['summary', 'status', 'priority', 'assignee', 'updated']);
        
        // Apply maxResults limit (default 50, max 100)
        const limit = Math.min(maxResults || 50, 100);
        const limitedIssues = issues.slice(0, limit);
        
        // Map to include assignee display name
        const mappedIssues = limitedIssues.map(issue => ({
          key: issue.key,
          summary: issue.summary,
          status: issue.status,
          priority: issue.priority,
          assignee: issue.assignee,
          updated: issue.updated,
        }));
  
        const output = { issues: mappedIssues, total: issues.length };
        return {
          content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
          structuredContent: output,
        };
      } catch (error) {
        const errOutput = formatError(error);
        return {
          content: [{ type: 'text', text: JSON.stringify(errOutput, null, 2) }],
          structuredContent: errOutput,
          isError: true,
        };
      }
    }

• src/jira-client.ts:241-277 (helper)

  Core helper function implementing the Jira JQL search via the /search/jql API endpoint, handling fields parameter, response parsing, and mapping to simplified JiraIssue format. Called by the tool handler.

  export async function searchIssues(jql: string, fields: string[] = ['summary', 'status', 'priority', 'updated']): Promise<JiraIssue[]> {
    const params = new URLSearchParams({
      jql,
      maxResults: '100',
    });
    // Add fields as separate params (the new API accepts array-style)
    fields.forEach(f => params.append('fields', f));
  
    const response = await jiraFetch<{
      issues: Array<{
        key: string;
        id: string;
        fields: {
          summary: string;
          status: { name: string };
          priority: { name: string };
          updated: string;
          description?: unknown;
          assignee?: { displayName: string; accountId: string };
          reporter?: { displayName: string; accountId: string };
          created?: string;
          comment?: { comments: Array<{ id: string; author: { displayName: string }; body: unknown; created: string; updated: string }> };
        };
      }>;
      isLast?: boolean;
      nextPageToken?: string;
    }>(`/search/jql?${params.toString()}`);
  
    return response.issues.map((issue) => ({
      key: issue.key,
      summary: issue.fields.summary,
      status: issue.fields.status.name,
      priority: issue.fields.priority?.name || 'None',
      updated: issue.fields.updated,
      assignee: issue.fields.assignee?.displayName,
    }));
  }