Skip to main content
Glama
joshuayoes

iOS Simulator MCP

by joshuayoes
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

record_video

Records video from an iOS Simulator using simctl. Specify codec, display, mask, and output path to capture screen activity.

Instructions

Records a video of the iOS Simulator using simctl directly

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
udidNoUdid of target, can also be set with the IDB_UDID env var
output_pathNoOptional output path. If not provided, a default name will be used. The file will be saved in the directory specified by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` or in `~/Downloads` if the environment variable is not set.
codecNoSpecifies the codec type: "h264" or "hevc". Default is "hevc".
displayNoDisplay to capture: "internal" or "external". Default depends on device type.
maskNoFor non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black".
forceNoForce the output file to be written to, even if the file already exists.

Implementation Reference

  • src/index.ts:977-1058 (handler)
    The handler function that executes the 'record_video' tool logic. It spawns an xcrun simctl io recordVideo process, waits for the 'Recording started' message, and returns the output path. Uses helper functions getBootedDeviceId, ensureAbsolutePath, and errorWithTroubleshooting.
      async ({ udid, output_path, codec, display, mask, force }) => {
    try {
      const actualUdid = await getBootedDeviceId(udid);
      const defaultFileName = `simulator_recording_${Date.now()}.mp4`;
      const outputFile = ensureAbsolutePath(output_path ?? defaultFileName);

      // Start the recording process
      const recordingProcess = spawn("xcrun", [
        "simctl",
        "io",
        actualUdid,
        "recordVideo",
        ...(codec ? [`--codec=${codec}`] : []),
        ...(display ? [`--display=${display}`] : []),
        ...(mask ? [`--mask=${mask}`] : []),
        ...(force ? ["--force"] : []),
        // When passing user-provided values to a command, it's crucial to use `--`
        // to separate the command's options from positional arguments.
        // This prevents the shell from misinterpreting the arguments as options.
        "--",
        outputFile,
      ]);

      // Wait for recording to start or fail within 5 seconds
      await new Promise((resolve, reject) => {
        let errorOutput = "";
        let resolved = false;

        recordingProcess.stderr.on("data", (data) => {
          const message = data.toString();
          if (message.includes("Recording started")) {
            resolved = true;
            resolve(true);
          } else {
            errorOutput += message;
          }
        });

        recordingProcess.on("exit", (code) => {
          if (!resolved) {
            reject(new Error(
              errorOutput.trim() || `Recording process exited early with code ${code}`
            ));
          }
        });

        setTimeout(() => {
          if (!resolved) {
            if (recordingProcess.killed || recordingProcess.exitCode !== null) {
              reject(new Error(errorOutput.trim() || "Recording process terminated unexpectedly"));
            } else {
              // Process still running but no "Recording started" message — assume it started
              resolve(true);
            }
          }
        }, 5000);
      });

      return {
        isError: false,
        content: [
          {
            type: "text",
            text: `Recording started. The video will be saved to: ${outputFile}\nTo stop recording, use the stop_recording command.`,
          },
        ],
      };
    } catch (error) {
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: errorWithTroubleshooting(
              `Error starting recording: ${toError(error).message}`
            ),
          },
        ],
      };
    }
  }
);
  • src/index.ts:938-975 (schema)
    Input schema definition for the 'record_video' tool. Defines parameters: udid (optional UUID string), output_path (optional string), codec (h264/hevc), display (internal/external), mask (ignored/alpha/black), force (boolean).
    {
  udid: z
    .string()
    .regex(UDID_REGEX)
    .optional()
    .describe("Udid of target, can also be set with the IDB_UDID env var"),
  output_path: z
    .string()
    .max(1024)
    .optional()
    .describe(
      `Optional output path. If not provided, a default name will be used. The file will be saved in the directory specified by \`IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR\` or in \`~/Downloads\` if the environment variable is not set.`
    ),
  codec: z
    .enum(["h264", "hevc"])
    .optional()
    .describe(
      'Specifies the codec type: "h264" or "hevc". Default is "hevc".'
    ),
  display: z
    .enum(["internal", "external"])
    .optional()
    .describe(
      'Display to capture: "internal" or "external". Default depends on device type.'
    ),
  mask: z
    .enum(["ignored", "alpha", "black"])
    .optional()
    .describe(
      'For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black".'
    ),
  force: z
    .boolean()
    .optional()
    .describe(
      "Force the output file to be written to, even if the file already exists."
    ),
},
  • src/index.ts:934-1059 (registration)
    Registration of the 'record_video' tool on the MCP server, conditionally gated by isToolFiltered check. Uses server.tool() with the tool name, description, input schema, and handler function.
    if (!isToolFiltered("record_video")) {
  server.tool(
    "record_video",
    "Records a video of the iOS Simulator using simctl directly",
    {
      udid: z
        .string()
        .regex(UDID_REGEX)
        .optional()
        .describe("Udid of target, can also be set with the IDB_UDID env var"),
      output_path: z
        .string()
        .max(1024)
        .optional()
        .describe(
          `Optional output path. If not provided, a default name will be used. The file will be saved in the directory specified by \`IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR\` or in \`~/Downloads\` if the environment variable is not set.`
        ),
      codec: z
        .enum(["h264", "hevc"])
        .optional()
        .describe(
          'Specifies the codec type: "h264" or "hevc". Default is "hevc".'
        ),
      display: z
        .enum(["internal", "external"])
        .optional()
        .describe(
          'Display to capture: "internal" or "external". Default depends on device type.'
        ),
      mask: z
        .enum(["ignored", "alpha", "black"])
        .optional()
        .describe(
          'For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black".'
        ),
      force: z
        .boolean()
        .optional()
        .describe(
          "Force the output file to be written to, even if the file already exists."
        ),
    },
    { title: "Record Video", readOnlyHint: false, openWorldHint: true },
    async ({ udid, output_path, codec, display, mask, force }) => {
      try {
        const actualUdid = await getBootedDeviceId(udid);
        const defaultFileName = `simulator_recording_${Date.now()}.mp4`;
        const outputFile = ensureAbsolutePath(output_path ?? defaultFileName);

        // Start the recording process
        const recordingProcess = spawn("xcrun", [
          "simctl",
          "io",
          actualUdid,
          "recordVideo",
          ...(codec ? [`--codec=${codec}`] : []),
          ...(display ? [`--display=${display}`] : []),
          ...(mask ? [`--mask=${mask}`] : []),
          ...(force ? ["--force"] : []),
          // When passing user-provided values to a command, it's crucial to use `--`
          // to separate the command's options from positional arguments.
          // This prevents the shell from misinterpreting the arguments as options.
          "--",
          outputFile,
        ]);

        // Wait for recording to start or fail within 5 seconds
        await new Promise((resolve, reject) => {
          let errorOutput = "";
          let resolved = false;

          recordingProcess.stderr.on("data", (data) => {
            const message = data.toString();
            if (message.includes("Recording started")) {
              resolved = true;
              resolve(true);
            } else {
              errorOutput += message;
            }
          });

          recordingProcess.on("exit", (code) => {
            if (!resolved) {
              reject(new Error(
                errorOutput.trim() || `Recording process exited early with code ${code}`
              ));
            }
          });

          setTimeout(() => {
            if (!resolved) {
              if (recordingProcess.killed || recordingProcess.exitCode !== null) {
                reject(new Error(errorOutput.trim() || "Recording process terminated unexpectedly"));
              } else {
                // Process still running but no "Recording started" message — assume it started
                resolve(true);
              }
            }
          }, 5000);
        });

        return {
          isError: false,
          content: [
            {
              type: "text",
              text: `Recording started. The video will be saved to: ${outputFile}\nTo stop recording, use the stop_recording command.`,
            },
          ],
        };
      } catch (error) {
        return {
          isError: true,
          content: [
            {
              type: "text",
              text: errorWithTroubleshooting(
                `Error starting recording: ${toError(error).message}`
              ),
            },
          ],
        };
      }
    }
  );
}
  • src/index.ts:195-208 (helper)
    Helper function getBootedDeviceId used by record_video handler to resolve the simulator UDID, falling back to the currently booted device if not provided.
    async function getBootedDeviceId(
  deviceId: string | undefined
): Promise<string> {
  // If deviceId not provided, get the currently booted simulator
  let actualDeviceId = deviceId;
  if (!actualDeviceId) {
    const { id } = await getBootedDevice();
    actualDeviceId = id;
  }
  if (!actualDeviceId) {
    throw new Error("No booted simulator found and no deviceId provided");
  }
  return actualDeviceId;
}
  • src/index.ts:819-844 (helper)
    Helper function ensureAbsolutePath used by record_video handler to resolve the output file path, expanding tilde and using the IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR env var or ~/Downloads as fallback.
    function ensureAbsolutePath(filePath: string): string {
  if (path.isAbsolute(filePath)) {
    return filePath;
  }

  // Handle ~/something paths in the provided filePath
  if (filePath.startsWith("~/")) {
    return path.join(os.homedir(), filePath.slice(2));
  }

  // Determine the default directory from env var or fallback to ~/Downloads
  let defaultDir = path.join(os.homedir(), "Downloads");
  const customDefaultDir = process.env.IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR;

  if (customDefaultDir) {
    // also expand tilde for the custom directory path
    if (customDefaultDir.startsWith("~/")) {
      defaultDir = path.join(os.homedir(), customDefaultDir.slice(2));
    } else {
      defaultDir = customDefaultDir;
    }
  }

  // Join the relative filePath with the resolved default directory
  return path.join(defaultDir, filePath);
}

Tool Definition Quality

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate mutation (readOnlyHint=false) but no additional behavioral traits are disclosed. The description adds no context about recording duration, blocking behavior, error states, or required permissions beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at 10 words and front-loads the key action. However, given the tool has six parameters and a sibling for stopping recording, a slightly expanded description could improve clarity without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool lacks an output schema and the description does not explain how the recording ends, how to stop it, or what happens to the output. The existence of the sibling stop_recording tool partially compensates, but the description should mention that this tool starts a recording that must be stopped separately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the schema already describes all parameters well. The description adds no extra meaning beyond the one-line statement. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Records a video'), the target resource ('iOS Simulator'), and the mechanism ('using simctl directly'). It distinguishes itself from sibling tools like screenshot and stop_recording.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for recording videos but provides no explicit guidance on when to use it versus alternatives or when not to use it. No mention of prerequisites or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/joshuayoes/ios-simulator-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server