Pinata MCP

Instructions

Implementation Reference

• src/index.ts:1555-1614 (registration)

  Tool registration and handler for pinByCid - pins existing CID from IPFS to Pinata account with optional metadata, group assignment, and host nodes specification

  server.tool(
    "pinByCid",
    "Pin an existing CID from the IPFS network to your Pinata account",
    {
      cid: z.string().describe("CID of the file you want to pin"),
      name: z.string().optional().describe("Custom name for the file"),
      group_id: z.string().optional().describe("ID of the group to add the file to"),
      keyvalues: z
        .record(z.string())
        .optional()
        .describe("Metadata key-value pairs for the file"),
      host_nodes: z
        .array(z.string())
        .optional()
        .describe("Array of host node IDs to fetch from"),
    },
    async ({ cid, name, group_id, keyvalues, host_nodes }) => {
      try {
        const url = "https://api.pinata.cloud/v3/files/public/pin_by_cid";
  
        const payload: {
          cid: string;
          name?: string;
          group_id?: string;
          keyvalues?: Record<string, string>;
          host_nodes?: string[];
        } = { cid };
  
        if (name) payload.name = name;
        if (group_id) payload.group_id = group_id;
        if (keyvalues) payload.keyvalues = keyvalues;
        if (host_nodes) payload.host_nodes = host_nodes;
  
        const response = await fetch(url, {
          method: "POST",
          headers: getHeaders(),
          body: JSON.stringify(payload),
        });
  
        if (!response.ok) {
          const errorText = await response.text();
          throw new Error(
            `Failed to pin CID: ${response.status} ${response.statusText}\n${errorText}`
          );
        }
  
        const data = await response.json();
        return {
          content: [
            {
              type: "text",
              text: `✅ Pin request queued!\n\n${JSON.stringify(data, null, 2)}`,
            },
          ],
        };
      } catch (error) {
        return errorResponse(error);
      }
    }
  );