Pinata MCP

Instructions

Implementation Reference

• src/index.ts:186-213 (handler)

  Handler function that executes the searchFiles tool logic - constructs API query parameters, calls the Pinata API to search files by name/CID/MIME type, and returns the results

  async ({ network, name, cid, mimeType, limit, pageToken }) => {
    try {
      const params = new URLSearchParams();
      if (name) params.append("name", name);
      if (cid) params.append("cid", cid);
      if (mimeType) params.append("mimeType", mimeType);
      if (limit) params.append("limit", limit.toString());
      if (pageToken) params.append("pageToken", pageToken);
  
      const url = `https://api.pinata.cloud/v3/files/${network}?${params.toString()}`;
  
      const response = await fetch(url, {
        method: "GET",
        headers: getHeaders(),
      });
  
      if (!response.ok) {
        throw new Error(
          `Failed to search files: ${response.status} ${response.statusText}`
        );
      }
  
      const data = await response.json();
      return successResponse(data);
    } catch (error) {
      return errorResponse(error);
    }
  }

• src/index.ts:172-185 (schema)

  Zod schema defining the input parameters for searchFiles: network (public/private), name, cid, mimeType, limit, and pageToken for filtering and pagination

  {
    network: z
      .enum(["public", "private"])
      .default("public")
      .describe("Whether to search in public or private IPFS"),
    name: z.string().optional().describe("Filter by filename"),
    cid: z.string().optional().describe("Filter by content ID (CID)"),
    mimeType: z.string().optional().describe("Filter by MIME type"),
    limit: z
      .number()
      .optional()
      .describe("Maximum number of results to return"),
    pageToken: z.string().optional().describe("Token for pagination"),
  },

• src/index.ts:169-214 (registration)

  Tool registration using server.tool() with name 'searchFiles', description, input schema, and async handler function

  server.tool(
    "searchFiles",
    "Search for files in your Pinata account by name, CID, or MIME type. Returns a list of files matching the given criteria.",
    {
      network: z
        .enum(["public", "private"])
        .default("public")
        .describe("Whether to search in public or private IPFS"),
      name: z.string().optional().describe("Filter by filename"),
      cid: z.string().optional().describe("Filter by content ID (CID)"),
      mimeType: z.string().optional().describe("Filter by MIME type"),
      limit: z
        .number()
        .optional()
        .describe("Maximum number of results to return"),
      pageToken: z.string().optional().describe("Token for pagination"),
    },
    async ({ network, name, cid, mimeType, limit, pageToken }) => {
      try {
        const params = new URLSearchParams();
        if (name) params.append("name", name);
        if (cid) params.append("cid", cid);
        if (mimeType) params.append("mimeType", mimeType);
        if (limit) params.append("limit", limit.toString());
        if (pageToken) params.append("pageToken", pageToken);
  
        const url = `https://api.pinata.cloud/v3/files/${network}?${params.toString()}`;
  
        const response = await fetch(url, {
          method: "GET",
          headers: getHeaders(),
        });
  
        if (!response.ok) {
          throw new Error(
            `Failed to search files: ${response.status} ${response.statusText}`
          );
        }
  
        const data = await response.json();
        return successResponse(data);
      } catch (error) {
        return errorResponse(error);
      }
    }
  );

• src/index.ts:100-108 (helper)

  Helper function getHeaders() that returns the Authorization header with Bearer token for authenticated API requests to Pinata

  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)

  Helper function successResponse() that formats successful API responses as text content with JSON stringified data

  const successResponse = (data: unknown) => ({
    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
  });