list_board_sprints

Retrieve sprints for a Jira board with filtering options for active, future, or closed states. Supports pagination to manage large result sets.

Instructions

List sprints for a given board with optional state filter.

Input Schema

TableJSON Schema

Name	Required	Description
`boardId`	Yes	Board ID
`state`	No	Sprint state filter
`startAt`	No	Pagination start index (default 0)
`maxResults`	No	Page size (1-100, default 50)

Implementation Reference

src/server.ts:376-407 (registration)

Registration of the 'list_board_sprints' MCP tool, including schema and inline handler implementation.

mcp.registerTool(
  "list_board_sprints",
  {
    title: "List Board Sprints",
    description: "List sprints for a given board with optional state filter.",
    inputSchema: {
      boardId: z.number().int().describe("Board ID"),
      state: z.enum(["active","future","closed"]).optional().describe("Sprint state filter"),
      startAt: z.number().int().min(0).optional().describe("Pagination start index (default 0)"),
      maxResults: z.number().int().min(1).max(100).optional().describe("Page size (1-100, default 50)"),
    },
  },
  async (args: { boardId: number; state?: "active"|"future"|"closed"; startAt?: number; maxResults?: number }) => {
    try {
      const params = new URLSearchParams();
      if (args.state) params.set("state", args.state);
      if (typeof args.startAt === "number") params.set("startAt", String(args.startAt));
      if (typeof args.maxResults === "number") params.set("maxResults", String(args.maxResults));
      const url = `${JIRA_URL}/rest/agile/1.0/board/${args.boardId}/sprint${params.toString() ? `?${params.toString()}` : ""}`;
      const response = await fetch(url, { method: "GET", headers: getJiraHeaders() });
      if (!response.ok) {
        const errorText = await response.text();
        return { content: [{ type: "text", text: `Failed to list sprints for board ${args.boardId}: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
      }
      const data = await response.json() as any;
      const sprints = (data.values || []).map((s: any) => ({ id: s.id, name: s.name, state: s.state, startDate: s.startDate, endDate: s.endDate, completeDate: s.completeDate }));
      return { content: [{ type: "text", text: `Found ${data.total ?? sprints.length} sprints (showing ${sprints.length}).` }], structuredContent: { total: data.total ?? sprints.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? sprints.length, boardId: args.boardId, sprints, raw: data } };
    } catch (error) {
      return { content: [{ type: "text", text: `Error listing sprints for board ${args.boardId}: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
    }
  }
);

src/server.ts:388-406 (handler)

Handler function that fetches and processes sprints for a specified Jira board using the REST Agile API, handling pagination and errors.

async (args: { boardId: number; state?: "active"|"future"|"closed"; startAt?: number; maxResults?: number }) => {
  try {
    const params = new URLSearchParams();
    if (args.state) params.set("state", args.state);
    if (typeof args.startAt === "number") params.set("startAt", String(args.startAt));
    if (typeof args.maxResults === "number") params.set("maxResults", String(args.maxResults));
    const url = `${JIRA_URL}/rest/agile/1.0/board/${args.boardId}/sprint${params.toString() ? `?${params.toString()}` : ""}`;
    const response = await fetch(url, { method: "GET", headers: getJiraHeaders() });
    if (!response.ok) {
      const errorText = await response.text();
      return { content: [{ type: "text", text: `Failed to list sprints for board ${args.boardId}: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
    }
    const data = await response.json() as any;
    const sprints = (data.values || []).map((s: any) => ({ id: s.id, name: s.name, state: s.state, startDate: s.startDate, endDate: s.endDate, completeDate: s.completeDate }));
    return { content: [{ type: "text", text: `Found ${data.total ?? sprints.length} sprints (showing ${sprints.length}).` }], structuredContent: { total: data.total ?? sprints.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? sprints.length, boardId: args.boardId, sprints, raw: data } };
  } catch (error) {
    return { content: [{ type: "text", text: `Error listing sprints for board ${args.boardId}: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
  }
}

src/server.ts:378-386 (schema)

Input schema definition using Zod for validating tool arguments: board ID, optional state filter, and pagination parameters.

{
  title: "List Board Sprints",
  description: "List sprints for a given board with optional state filter.",
  inputSchema: {
    boardId: z.number().int().describe("Board ID"),
    state: z.enum(["active","future","closed"]).optional().describe("Sprint state filter"),
    startAt: z.number().int().min(0).optional().describe("Pagination start index (default 0)"),
    maxResults: z.number().int().min(1).max(100).optional().describe("Page size (1-100, default 50)"),
  },

Jira MCP Server