listGroups
Retrieve and filter groups from your Pinata IPFS account to organize and manage stored content efficiently.
Instructions
List groups in your Pinata account with optional filtering by name
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Whether to list groups in public or private IPFS | public |
| name | No | Filter groups by name | |
| limit | No | Maximum number of results to return | |
| pageToken | No | Token for pagination |
Implementation Reference
- src/index.ts:679-720 (handler)Main implementation of the listGroups tool. Registers the MCP tool with schema validation for network (public/private), name filter, limit, and pageToken parameters. The handler builds query parameters and makes a GET request to the Pinata API to list groups.
server.tool( "listGroups", "List groups in your Pinata account with optional filtering by name", { network: z .enum(["public", "private"]) .default("public") .describe("Whether to list groups in public or private IPFS"), name: z.string().optional().describe("Filter groups by name"), limit: z .number() .optional() .describe("Maximum number of results to return"), pageToken: z.string().optional().describe("Token for pagination"), }, async ({ network, name, limit, pageToken }) => { try { const params = new URLSearchParams(); if (name) params.append("name", name); if (limit) params.append("limit", limit.toString()); if (pageToken) params.append("pageToken", pageToken); const url = `https://api.pinata.cloud/v3/groups/${network}?${params.toString()}`; const response = await fetch(url, { method: "GET", headers: getHeaders(), }); if (!response.ok) { throw new Error( `Failed to list groups: ${response.status} ${response.statusText}` ); } const data = await response.json(); return successResponse(data); } catch (error) { return errorResponse(error); } } ); - src/index.ts:100-108 (helper)getHeaders() helper function that constructs authorization headers for Pinata API requests, used by listGroups handler to authenticate API calls.
const getHeaders = () => { if (!PINATA_JWT) { throw new Error("PINATA_JWT environment variable is not set"); } return { Authorization: `Bearer ${PINATA_JWT}`, "Content-Type": "application/json", }; }; - src/index.ts:122-124 (helper)successResponse() helper function that formats successful API responses as MCP content with JSON formatting, used by listGroups to return group data.
const successResponse = (data: unknown) => ({ content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }], }); - src/index.ts:111-119 (helper)errorResponse() helper function that formats error messages for MCP content, used by listGroups to handle and return API errors.
const errorResponse = (error: unknown) => ({ content: [ { type: "text" as const, text: `Error: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, });