appium-mcp 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.33.0](https://github.com/appium/appium-mcp/compare/v1.32.0...v1.33.0) (2026-03-22)
+
+### Features
+
+* **session:** add appium_mobile_push_file and appium_mobile_pull_file ([#222](https://github.com/appium/appium-mcp/issues/222)) ([8eb1f8d](https://github.com/appium/appium-mcp/commit/8eb1f8dab342b844a54aa90f0744f7586a1d9dc7))
+
 ## [1.32.0](https://github.com/appium/appium-mcp/compare/v1.31.0...v1.32.0) (2026-03-21)
 
 ### Features

package/dist/tests/tools/session/file-transfer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-transfer.test.d.ts.map

package/dist/tests/tools/session/file-transfer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transfer.test.d.ts","sourceRoot":"","sources":["../../../../src/tests/tools/session/file-transfer.test.ts"],"names":[],"mappings":""}

package/dist/tests/tools/session/file-transfer.test.js

@@ -0,0 +1,87 @@
+import { describe, test, expect, jest, beforeEach } from '@jest/globals';
+jest.unstable_mockModule('../../../session-store', () => ({
+    getDriver: jest.fn(),
+    getPlatformName: jest.fn(),
+    PLATFORM: { ios: 'iOS', android: 'Android' },
+}));
+jest.unstable_mockModule('../../../command', () => ({
+    execute: jest.fn(),
+}));
+jest.unstable_mockModule('../../../logger', () => ({
+    default: { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } },
+}));
+const { getDriver, getPlatformName, PLATFORM } = await import('../../../session-store.js');
+const { execute } = await import('../../../command.js');
+const mockGetDriver = getDriver;
+const mockGetPlatformName = getPlatformName;
+const mockExecute = execute;
+describe('appium_mobile_push_file / appium_mobile_pull_file', () => {
+    const mockServer = { addTool: jest.fn() };
+    beforeEach(() => {
+        mockServer.addTool.mockClear();
+        mockExecute.mockReset();
+    });
+    test('push: throws when no driver is active', async () => {
+        const { pushFile } = await import('../../../tools/session/file-transfer.js');
+        mockGetDriver.mockReturnValue(null);
+        pushFile(mockServer);
+        const tool = mockServer.addTool.mock.calls.at(-1)?.[0];
+        await expect(tool.execute({ remotePath: '/sdcard/x.txt', payloadBase64: 'YQ==' }, undefined)).rejects.toThrow('No driver found');
+    });
+    test('push: Android uses path and data', async () => {
+        const { pushFile } = await import('../../../tools/session/file-transfer.js');
+        mockGetDriver.mockReturnValue({});
+        mockGetPlatformName.mockReturnValue(PLATFORM.android);
+        mockExecute.mockResolvedValue(undefined);
+        pushFile(mockServer);
+        const tool = mockServer.addTool.mock.calls.at(-1)?.[0];
+        await tool.execute({ remotePath: '/data/local/tmp/a.txt', payloadBase64: 'SGVsbG8=' }, undefined);
+        expect(mockExecute).toHaveBeenCalledWith(expect.anything(), 'mobile: pushFile', expect.objectContaining({
+            path: '/data/local/tmp/a.txt',
+            data: 'SGVsbG8=',
+        }));
+    });
+    test('push: iOS uses remotePath and payload', async () => {
+        const { pushFile } = await import('../../../tools/session/file-transfer.js');
+        mockGetDriver.mockReturnValue({});
+        mockGetPlatformName.mockReturnValue(PLATFORM.ios);
+        mockExecute.mockResolvedValue(undefined);
+        pushFile(mockServer);
+        const tool = mockServer.addTool.mock.calls.at(-1)?.[0];
+        await tool.execute({
+            remotePath: '@com.example.app:documents/x.txt',
+            payloadBase64: 'QQ==',
+        }, undefined);
+        expect(mockExecute).toHaveBeenCalledWith(expect.anything(), 'mobile: pushFile', expect.objectContaining({
+            remotePath: '@com.example.app:documents/x.txt',
+            payload: 'QQ==',
+        }));
+    });
+    test('pull: Android uses path', async () => {
+        const { pullFile } = await import('../../../tools/session/file-transfer.js');
+        mockGetDriver.mockReturnValue({});
+        mockGetPlatformName.mockReturnValue(PLATFORM.android);
+        mockExecute.mockResolvedValue('YmJiYg==');
+        pullFile(mockServer);
+        const tool = mockServer.addTool.mock.calls.at(-1)?.[0];
+        const result = await tool.execute({ remotePath: '/sdcard/Download/out.bin' }, undefined);
+        expect(mockExecute).toHaveBeenCalledWith(expect.anything(), 'mobile: pullFile', expect.objectContaining({ path: '/sdcard/Download/out.bin' }));
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.contentBase64).toBe('YmJiYg==');
+        expect(parsed.platform).toBe('Android');
+    });
+    test('pull: iOS uses remotePath', async () => {
+        const { pullFile } = await import('../../../tools/session/file-transfer.js');
+        mockGetDriver.mockReturnValue({});
+        mockGetPlatformName.mockReturnValue(PLATFORM.ios);
+        mockExecute.mockResolvedValue('eHh4');
+        pullFile(mockServer);
+        const tool = mockServer.addTool.mock.calls.at(-1)?.[0];
+        const result = await tool.execute({ remotePath: '@com.app:documents/f.txt' }, undefined);
+        expect(mockExecute).toHaveBeenCalledWith(expect.anything(), 'mobile: pullFile', expect.objectContaining({ remotePath: '@com.app:documents/f.txt' }));
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.contentBase64).toBe('eHh4');
+        expect(parsed.platform).toBe('iOS');
+    });
+});
+//# sourceMappingURL=file-transfer.test.js.map

package/dist/tests/tools/session/file-transfer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transfer.test.js","sourceRoot":"","sources":["../../../../src/tests/tools/session/file-transfer.test.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAoDlC,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAyI3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAqDlC,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA2I3D"}

package/dist/tools/index.js

@@ -12,6 +12,7 @@ import { lockDevice, unlockDevice } from './session/lock.js';
 import { setGeolocation, getGeolocation, resetGeolocation, } from './session/geolocation.js';
 import deviceInfo from './session/device-info.js';
 import batteryInfo from './session/battery-info.js';
+import { pushFile, pullFile } from './session/file-transfer.js';
 import bootSimulator from './ios/boot-simulator.js';
 import setupWDA from './ios/setup-wda.js';
 import installWDA from './ios/install-wda.js';
@@ -121,6 +122,8 @@ export default function registerTools(server) {
     resetGeolocation(server);
     deviceInfo(server);
     batteryInfo(server);
+    pushFile(server);
+    pullFile(server);
     // iOS Setup
     bootSimulator(server);
     setupWDA(server);

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/session/file-transfer.d.ts

@@ -0,0 +1,13 @@
+import type { FastMCP } from 'fastmcp';
+/**
+ * Push a file from the host (MCP client) to the device via `mobile: pushFile`.
+ *
+ * - Android: `{ path, data }` per UiAutomator2 / legacy JSONWP push_file.
+ * - iOS: `{ remotePath, payload }` per XCUITest execute-methods reference.
+ */
+export declare function pushFile(server: FastMCP): void;
+/**
+ * Pull a file from the device via `mobile: pullFile`. Returns Base64-encoded content in the response text.
+ */
+export declare function pullFile(server: FastMCP): void;
+//# sourceMappingURL=file-transfer.d.ts.map

package/dist/tools/session/file-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transfer.d.ts","sourceRoot":"","sources":["../../../src/tools/session/file-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AAiCtD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAkE9C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAqE9C"}

package/dist/tools/session/file-transfer.js

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import { execute } from '../../command.js';
+/**
+ * Normalize the return value of mobile: pullFile (driver may return a string
+ * or a wrapped value depending on client/driver).
+ */
+function normalizePullResult(result) {
+    if (typeof result === 'string') {
+        return result;
+    }
+    if (result &&
+        typeof result === 'object' &&
+        'value' in result &&
+        typeof result.value === 'string') {
+        return result.value;
+    }
+    return String(result ?? '');
+}
+const remotePathDescription = 'Path to the file on the device. ' +
+    'Android (UiAutomator2): use an absolute path (e.g. /data/local/tmp/foo.txt or /sdcard/Download/foo.txt). ' +
+    'iOS (XCUITest): use the formats described in the Appium XCUITest file transfer guide ' +
+    '(e.g. @com.example.app:documents/file.txt or simulator-relative paths).';
+const payloadDescription = 'File contents encoded as Base64 (raw base64 only; do not include a data: URL prefix).';
+/**
+ * Push a file from the host (MCP client) to the device via `mobile: pushFile`.
+ *
+ * - Android: `{ path, data }` per UiAutomator2 / legacy JSONWP push_file.
+ * - iOS: `{ remotePath, payload }` per XCUITest execute-methods reference.
+ */
+export function pushFile(server) {
+    const schema = z.object({
+        remotePath: z.string().min(1).describe(remotePathDescription),
+        payloadBase64: z.string().min(1).describe(payloadDescription),
+    });
+    server.addTool({
+        name: 'appium_mobile_push_file',
+        description: 'Push a file to the device using the Appium `mobile: pushFile` extension. ' +
+            'Android uses `path` + `data` (base64). iOS uses `remotePath` + `payload` (base64). ' +
+            'Path semantics on iOS follow the XCUITest file transfer guide (app containers, documents, simulator paths). ' +
+            'Large payloads produce large requests; avoid pushing huge files through MCP.',
+        parameters: schema,
+        annotations: {
+            readOnlyHint: false,
+            openWorldHint: false,
+        },
+        execute: async (args, _context) => {
+            const driver = getDriver();
+            if (!driver) {
+                throw new Error('No driver found');
+            }
+            try {
+                const platform = getPlatformName(driver);
+                if (platform === PLATFORM.android) {
+                    await execute(driver, 'mobile: pushFile', {
+                        path: args.remotePath,
+                        data: args.payloadBase64,
+                    });
+                }
+                else if (platform === PLATFORM.ios) {
+                    await execute(driver, 'mobile: pushFile', {
+                        remotePath: args.remotePath,
+                        payload: args.payloadBase64,
+                    });
+                }
+                else {
+                    throw new Error(`Unsupported platform: ${platform}. Only Android and iOS are supported.`);
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Successfully pushed file to device path: ${args.remotePath}`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Failed to push file. err: ${message}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}
+/**
+ * Pull a file from the device via `mobile: pullFile`. Returns Base64-encoded content in the response text.
+ */
+export function pullFile(server) {
+    const schema = z.object({
+        remotePath: z.string().min(1).describe(remotePathDescription),
+    });
+    server.addTool({
+        name: 'appium_mobile_pull_file',
+        description: 'Pull a file from the device using the Appium `mobile: pullFile` extension. ' +
+            'Returns Base64-encoded file content in the response text. ' +
+            'Android uses parameter `path`; iOS uses `remotePath` with the same path formats as push. ' +
+            'Very large files may produce very large responses; prefer downloading or streaming outside MCP for big binaries.',
+        parameters: schema,
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        execute: async (args, _context) => {
+            const driver = getDriver();
+            if (!driver) {
+                throw new Error('No driver found');
+            }
+            try {
+                const platform = getPlatformName(driver);
+                let raw;
+                if (platform === PLATFORM.android) {
+                    raw = await execute(driver, 'mobile: pullFile', {
+                        path: args.remotePath,
+                    });
+                }
+                else if (platform === PLATFORM.ios) {
+                    raw = await execute(driver, 'mobile: pullFile', {
+                        remotePath: args.remotePath,
+                    });
+                }
+                else {
+                    throw new Error(`Unsupported platform: ${platform}. Only Android and iOS are supported.`);
+                }
+                const base64 = normalizePullResult(raw);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                remotePath: args.remotePath,
+                                platform,
+                                contentBase64: base64,
+                            }),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Failed to pull file. err: ${message}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}
+//# sourceMappingURL=file-transfer.js.map

package/dist/tools/session/file-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transfer.js","sourceRoot":"","sources":["../../../src/tools/session/file-transfer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.32.0",
+      "version": "1.33.0",
       "transport": {
         "type": "stdio"
       }

package/src/tests/tools/session/file-transfer.test.ts

@@ -0,0 +1,158 @@
+import { describe, test, expect, jest, beforeEach } from '@jest/globals';
+
+jest.unstable_mockModule('../../../session-store', () => ({
+  getDriver: jest.fn(),
+  getPlatformName: jest.fn(),
+  PLATFORM: { ios: 'iOS', android: 'Android' },
+}));
+
+jest.unstable_mockModule('../../../command', () => ({
+  execute: jest.fn(),
+}));
+
+jest.unstable_mockModule('../../../logger', () => ({
+  default: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+}));
+
+const { getDriver, getPlatformName, PLATFORM } =
+  await import('../../../session-store.js');
+const { execute } = await import('../../../command.js');
+
+const mockGetDriver = getDriver as jest.MockedFunction<typeof getDriver>;
+const mockGetPlatformName = getPlatformName as jest.MockedFunction<
+  typeof getPlatformName
+>;
+const mockExecute = execute as jest.MockedFunction<typeof execute>;
+
+describe('appium_mobile_push_file / appium_mobile_pull_file', () => {
+  const mockServer = { addTool: jest.fn() } as any;
+
+  beforeEach(() => {
+    (mockServer.addTool as jest.MockedFunction<any>).mockClear();
+    mockExecute.mockReset();
+  });
+
+  test('push: throws when no driver is active', async () => {
+    const { pushFile } =
+      await import('../../../tools/session/file-transfer.js');
+    mockGetDriver.mockReturnValue(null as any);
+    pushFile(mockServer);
+
+    const tool = (mockServer.addTool as jest.MockedFunction<any>).mock.calls.at(
+      -1
+    )?.[0];
+    await expect(
+      tool.execute(
+        { remotePath: '/sdcard/x.txt', payloadBase64: 'YQ==' },
+        undefined
+      )
+    ).rejects.toThrow('No driver found');
+  });
+
+  test('push: Android uses path and data', async () => {
+    const { pushFile } =
+      await import('../../../tools/session/file-transfer.js');
+    mockGetDriver.mockReturnValue({} as any);
+    mockGetPlatformName.mockReturnValue(PLATFORM.android);
+    mockExecute.mockResolvedValue(undefined);
+
+    pushFile(mockServer);
+    const tool = (mockServer.addTool as jest.MockedFunction<any>).mock.calls.at(
+      -1
+    )?.[0];
+    await tool.execute(
+      { remotePath: '/data/local/tmp/a.txt', payloadBase64: 'SGVsbG8=' },
+      undefined
+    );
+
+    expect(mockExecute).toHaveBeenCalledWith(
+      expect.anything(),
+      'mobile: pushFile',
+      expect.objectContaining({
+        path: '/data/local/tmp/a.txt',
+        data: 'SGVsbG8=',
+      })
+    );
+  });
+
+  test('push: iOS uses remotePath and payload', async () => {
+    const { pushFile } =
+      await import('../../../tools/session/file-transfer.js');
+    mockGetDriver.mockReturnValue({} as any);
+    mockGetPlatformName.mockReturnValue(PLATFORM.ios);
+    mockExecute.mockResolvedValue(undefined);
+
+    pushFile(mockServer);
+    const tool = (mockServer.addTool as jest.MockedFunction<any>).mock.calls.at(
+      -1
+    )?.[0];
+    await tool.execute(
+      {
+        remotePath: '@com.example.app:documents/x.txt',
+        payloadBase64: 'QQ==',
+      },
+      undefined
+    );
+
+    expect(mockExecute).toHaveBeenCalledWith(
+      expect.anything(),
+      'mobile: pushFile',
+      expect.objectContaining({
+        remotePath: '@com.example.app:documents/x.txt',
+        payload: 'QQ==',
+      })
+    );
+  });
+
+  test('pull: Android uses path', async () => {
+    const { pullFile } =
+      await import('../../../tools/session/file-transfer.js');
+    mockGetDriver.mockReturnValue({} as any);
+    mockGetPlatformName.mockReturnValue(PLATFORM.android);
+    mockExecute.mockResolvedValue('YmJiYg==');
+
+    pullFile(mockServer);
+    const tool = (mockServer.addTool as jest.MockedFunction<any>).mock.calls.at(
+      -1
+    )?.[0];
+    const result = await tool.execute(
+      { remotePath: '/sdcard/Download/out.bin' },
+      undefined
+    );
+
+    expect(mockExecute).toHaveBeenCalledWith(
+      expect.anything(),
+      'mobile: pullFile',
+      expect.objectContaining({ path: '/sdcard/Download/out.bin' })
+    );
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.contentBase64).toBe('YmJiYg==');
+    expect(parsed.platform).toBe('Android');
+  });
+
+  test('pull: iOS uses remotePath', async () => {
+    const { pullFile } =
+      await import('../../../tools/session/file-transfer.js');
+    mockGetDriver.mockReturnValue({} as any);
+    mockGetPlatformName.mockReturnValue(PLATFORM.ios);
+    mockExecute.mockResolvedValue('eHh4');
+
+    pullFile(mockServer);
+    const tool = (mockServer.addTool as jest.MockedFunction<any>).mock.calls.at(
+      -1
+    )?.[0];
+    const result = await tool.execute(
+      { remotePath: '@com.app:documents/f.txt' },
+      undefined
+    );
+
+    expect(mockExecute).toHaveBeenCalledWith(
+      expect.anything(),
+      'mobile: pullFile',
+      expect.objectContaining({ remotePath: '@com.app:documents/f.txt' })
+    );
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.contentBase64).toBe('eHh4');
+    expect(parsed.platform).toBe('iOS');
+  });
+});

package/src/tools/README.md

@@ -13,6 +13,7 @@ This directory contains all MCP tools available in MCP Appium.
 - `lock.ts` - Unlock device (`appium_mobile_unlock`)
 - `select-platform.ts` - Choose Android or iOS
 - `select-device.ts` - Choose specific device
+- `file-transfer.ts` - Push/pull files on device (`appium_mobile_push_file`, `appium_mobile_pull_file`)
 
 ### iOS Setup (`ios/`)
 

package/src/tools/index.ts

@@ -31,6 +31,7 @@ import {
 } from './session/geolocation.js';
 import deviceInfo from './session/device-info.js';
 import batteryInfo from './session/battery-info.js';
+import { pushFile, pullFile } from './session/file-transfer.js';
 import bootSimulator from './ios/boot-simulator.js';
 import setupWDA from './ios/setup-wda.js';
 import installWDA from './ios/install-wda.js';
@@ -146,6 +147,8 @@ export default function registerTools(server: FastMCP): void {
   resetGeolocation(server);
   deviceInfo(server);
   batteryInfo(server);
+  pushFile(server);
+  pullFile(server);
 
   // iOS Setup
   bootSimulator(server);

package/src/tools/session/file-transfer.ts

@@ -0,0 +1,180 @@
+import type { ContentResult, FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import { execute } from '../../command.js';
+
+/**
+ * Normalize the return value of mobile: pullFile (driver may return a string
+ * or a wrapped value depending on client/driver).
+ */
+function normalizePullResult(result: unknown): string {
+  if (typeof result === 'string') {
+    return result;
+  }
+  if (
+    result &&
+    typeof result === 'object' &&
+    'value' in result &&
+    typeof (result as { value: unknown }).value === 'string'
+  ) {
+    return (result as { value: string }).value;
+  }
+  return String(result ?? '');
+}
+
+const remotePathDescription =
+  'Path to the file on the device. ' +
+  'Android (UiAutomator2): use an absolute path (e.g. /data/local/tmp/foo.txt or /sdcard/Download/foo.txt). ' +
+  'iOS (XCUITest): use the formats described in the Appium XCUITest file transfer guide ' +
+  '(e.g. @com.example.app:documents/file.txt or simulator-relative paths).';
+
+const payloadDescription =
+  'File contents encoded as Base64 (raw base64 only; do not include a data: URL prefix).';
+
+/**
+ * Push a file from the host (MCP client) to the device via `mobile: pushFile`.
+ *
+ * - Android: `{ path, data }` per UiAutomator2 / legacy JSONWP push_file.
+ * - iOS: `{ remotePath, payload }` per XCUITest execute-methods reference.
+ */
+export function pushFile(server: FastMCP): void {
+  const schema = z.object({
+    remotePath: z.string().min(1).describe(remotePathDescription),
+    payloadBase64: z.string().min(1).describe(payloadDescription),
+  });
+
+  server.addTool({
+    name: 'appium_mobile_push_file',
+    description:
+      'Push a file to the device using the Appium `mobile: pushFile` extension. ' +
+      'Android uses `path` + `data` (base64). iOS uses `remotePath` + `payload` (base64). ' +
+      'Path semantics on iOS follow the XCUITest file transfer guide (app containers, documents, simulator paths). ' +
+      'Large payloads produce large requests; avoid pushing huge files through MCP.',
+    parameters: schema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (
+      args: z.infer<typeof schema>,
+      _context: Record<string, unknown> | undefined
+    ): Promise<ContentResult> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        const platform = getPlatformName(driver);
+        if (platform === PLATFORM.android) {
+          await execute(driver, 'mobile: pushFile', {
+            path: args.remotePath,
+            data: args.payloadBase64,
+          });
+        } else if (platform === PLATFORM.ios) {
+          await execute(driver, 'mobile: pushFile', {
+            remotePath: args.remotePath,
+            payload: args.payloadBase64,
+          });
+        } else {
+          throw new Error(
+            `Unsupported platform: ${platform}. Only Android and iOS are supported.`
+          );
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully pushed file to device path: ${args.remotePath}`,
+            },
+          ],
+        };
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to push file. err: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}
+
+/**
+ * Pull a file from the device via `mobile: pullFile`. Returns Base64-encoded content in the response text.
+ */
+export function pullFile(server: FastMCP): void {
+  const schema = z.object({
+    remotePath: z.string().min(1).describe(remotePathDescription),
+  });
+
+  server.addTool({
+    name: 'appium_mobile_pull_file',
+    description:
+      'Pull a file from the device using the Appium `mobile: pullFile` extension. ' +
+      'Returns Base64-encoded file content in the response text. ' +
+      'Android uses parameter `path`; iOS uses `remotePath` with the same path formats as push. ' +
+      'Very large files may produce very large responses; prefer downloading or streaming outside MCP for big binaries.',
+    parameters: schema,
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+    execute: async (
+      args: z.infer<typeof schema>,
+      _context: Record<string, unknown> | undefined
+    ): Promise<ContentResult> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        const platform = getPlatformName(driver);
+        let raw: unknown;
+        if (platform === PLATFORM.android) {
+          raw = await execute(driver, 'mobile: pullFile', {
+            path: args.remotePath,
+          });
+        } else if (platform === PLATFORM.ios) {
+          raw = await execute(driver, 'mobile: pullFile', {
+            remotePath: args.remotePath,
+          });
+        } else {
+          throw new Error(
+            `Unsupported platform: ${platform}. Only Android and iOS are supported.`
+          );
+        }
+
+        const base64 = normalizePullResult(raw);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({
+                remotePath: args.remotePath,
+                platform,
+                contentBase64: base64,
+              }),
+            },
+          ],
+        };
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to pull file. err: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}