Pinata MCP

Instructions

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,
  });