ig_get_media

Instructions

Implementation Reference

• src/tools/instagram/media.ts:31-47 (handler)

  The main tool handler for 'ig_get_media'. Defines the tool on the MCP server with schema (media_id required, fields optional) and async function that calls MetaClient.ig() to fetch media details.

  // ─── ig_get_media ────────────────────────────────────────────
  server.tool(
    "ig_get_media",
    "Get details of a specific Instagram media post.",
    {
      media_id: z.string().describe("Media ID"),
      fields: z.string().optional().describe("Comma-separated fields (default: id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count)"),
    },
    async ({ media_id, fields }) => {
      try {
        const f = fields || "id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,like_count,comments_count";
        const { data, rateLimit } = await client.ig("GET", `/${media_id}`, { fields: f });
        return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text", text: `Get media failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }

• src/tools/instagram/media.ts:5-48 (registration)

  The export function registerIgMediaTools() that registers 'ig_get_media' (and other media tools) on the McpServer instance.

  export function registerIgMediaTools(server: McpServer, client: MetaClient): void {
    // ─── ig_get_media_list ───────────────────────────────────────
    server.tool(
      "ig_get_media_list",
      "Get list of media published on the Instagram account.",
      {
        limit: z.number().optional().describe("Number of results (max 100, default 25)"),
        after: z.string().optional().describe("Pagination cursor for next page"),
        before: z.string().optional().describe("Pagination cursor for previous page"),
      },
      async ({ limit, after, before }) => {
        try {
          const params: Record<string, unknown> = {
            fields: "id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,like_count,comments_count",
          };
          if (limit) params.limit = limit;
          if (after) params.after = after;
          if (before) params.before = before;
          const { data, rateLimit } = await client.ig("GET", `/${client.igUserId}/media`, params);
          return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text", text: `Get media list failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── ig_get_media ────────────────────────────────────────────
    server.tool(
      "ig_get_media",
      "Get details of a specific Instagram media post.",
      {
        media_id: z.string().describe("Media ID"),
        fields: z.string().optional().describe("Comma-separated fields (default: id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count)"),
      },
      async ({ media_id, fields }) => {
        try {
          const f = fields || "id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,like_count,comments_count";
          const { data, rateLimit } = await client.ig("GET", `/${media_id}`, { fields: f });
          return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text", text: `Get media failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );

• src/tools/instagram/media.ts:35-38 (schema)

  Input schema for ig_get_media: media_id (required string) and fields (optional string) defined with Zod.

  {
    media_id: z.string().describe("Media ID"),
    fields: z.string().optional().describe("Comma-separated fields (default: id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count)"),
  },

• src/index.ts:43-43 (registration)

  Where registerIgMediaTools is called to attach the tool to the live MCP server.

  registerIgMediaTools(server, client);

• src/services/meta-client.ts:76-85 (helper)

  The MetaClient.ig() method that performs the actual Graph API request, called by the handler.

  async ig(
    method: string,
    path: string,
    params?: Record<string, unknown>
  ): Promise<ClientResponse> {
    if (!this.config.instagramAccessToken) {
      throw new Error("INSTAGRAM_ACCESS_TOKEN is not configured.");
    }
    return this.request(IG_BASE, this.config.instagramAccessToken, method, path, params);
  }