Skip to main content
Glama
Sign In
FilmoraMCP-Server

FilmoraMCP-Server

by SkieAdmin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

FilmoraMCP-Server

A local Windows MCP server targeting Wondershare Filmora X / version 10 and newer. It detects the selected editor at runtime, chooses compatible shortcut policies and resolves live UI controls instead of requiring one Filmora build. It gives an MCP assistant actual PNG screenshots, accessibility inspection, mouse/keyboard input, project dialogs, timeline commands, clip panels, media libraries, audio tools and export workflows.

Release 0.2.0 includes profiles for X/10 and 11–16, plus conservative adaptation for unknown/future versions. Local editor validation is currently on 13.6.13; other releases have adapter/policy tests and still need live editor validation. See docs/COMPATIBILITY.md for the matrix and limits.

This is independent software, not an official Wondershare integration. FilmoraMCP operates the visible editor. It does not expose a private editing API or rewrite undocumented .wfp files.

Product scope

Item

Current scope

Filmora target

Filmora X/v10 and newer on Windows; runtime detection selects the applicable profile

Version policies

X/10 legacy commands; release profiles for 11–16; conservative unknown/future adaptation

MCP clients

Claude Code, Claude Desktop, Codex and Google Antigravity; additional Cursor snippet

Interface

Local stdio MCP: 33 tools, 2 resources, 1 editing prompt

Catalog

94 command candidates, 39 named UI targets, 102 feature guides; availability varies by version/context

Evidence

66 automated tests passed; native editor testing on 13.6.13; complete edit/export validation remains outstanding

The product requirement is broad access to editing features through the live editor. Version-dependent features remain conditional on the installed build, selection, assets, account and license. See the PRD for requirements and acceptance criteria, and the roadmap for remaining validation work.

Related MCP server: openowl

Quickstart

From an extracted source folder, install the environment and preview client registration:

powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\connect-clients.ps1 -Preview

Register the selected clients with connect-clients.ps1 as described below, then reload their MCP connections. Run diagnostics with:

.\.venv\Scripts\python.exe -m filmora_mcp.server --diagnose

For stdio MCP, use the absolute Python executable and module argument from client-configs/. The MCP client starts the server; you normally do not double-click run.cmd first. Running run.cmd alone waits silently for JSON-RPC on stdin.

Connect a client

  • Claude Code / Claude Desktop / Codex / Google Antigravity: run connect-clients.ps1 to register Filmora in all four local clients. Existing settings and MCP servers are preserved; original configs are backed up under logs/client-backups. Repeat runs are safe and do not duplicate the server. Use connect-clients.ps1 -Preview to inspect target paths first.

  • For a specific client: .\.venv\Scripts\python.exe scripts\install_clients.py --clients antigravity --apply (choices: claude-code, claude-desktop, codex, antigravity).

  • Manual configurations are in client-configs/claude-code.json, claude-desktop.json, codex.toml and antigravity.json. Cursor's snippet remains included.

Reload MCP servers or restart each client after registration. Setup installs dependencies/snippets; registration is a separate step. The installer does not change trust/approval policies and refuses to replace a different existing filmora server. Claude support here means local Claude Code and Claude Desktop. See docs/CLIENTS.md for client paths, verification and troubleshooting.

Coverage

Area

Implemented control

Vision

Window PNG images returned as MCP ImageContent; crop, resize, saved captures; image-to-window coordinate mapping

Inspection

Window enumeration, process validation, accessibility names/IDs/types/geometry/focus, searchable control trees

Interaction

Single/double/right click, modifier-click, drag, scrolling, bounded shortcut repetition, literal Unicode text

UI controls

Focus, invoke, click, set text/value, select list/combo items, toggle, expand/collapse, numeric slider ranges

Project/media

Launch, new/open/save/save-as/archive commands, native file-dialog paths, import, media libraries, folders

Timeline

Split/trim, ripple delete, duplicate, grouping, insert/overwrite, navigation, markers, zoom, track toolbar

Video/color

Open properties, crop/zoom, speed, stabilization, chroma key, tracking, color correction/match and keyframes

Audio/text/assets

Audio mixer/recorder, detach/mute, titles, effects, transitions, filters, stickers, captions and AI toolbar targets

Export

Open export settings, inspect/configure/start through real controls, inspect progress and verify resulting file size

Advanced features

Feature-route catalog for masks, speed ramps, LUTs, denoise, ducking, subtitles, AI and other version-dependent tools

Run filmora_status for detected executable versions and filmora_capabilities(probe_ui=true) for version-resolved commands plus exposed/disabled UI targets. filmora_commands filters commands by group/text and omits unavailable ones by default. Its include_unavailable=true option explains blocked commands.

Coverage means access through Filmora's UI, not that every feature has a one-call editing API. Detailed effect parameters, exact clip timing, text styling, export settings and AI operations are configured using live inspected controls or screenshots. Feature guides describe navigation; they do not execute edits. Version checks flag known newer features on older editors; other features remain unverified until inspected. The installed release, shortcut preset, clip selection, layout, assets and license determine availability. Premium/AI features may require login, network processing, credits or downloads; the server does not supply those entitlements.

Typical request

Inspect my Filmora project, import these clips, arrange them on the timeline, trim the first clip, add a title and transition, adjust audio, save as a new project, and export a local MP4. Check screenshots after each important change.

The assistant starts with filmora_status, filmora_windows, filmora_screenshot and filmora_inspect, acts once, and checks the result. See docs/WORKFLOWS.md for tool sequences.

Install or move to another computer

Requires 64-bit Windows, Python 3.11+ and installed Filmora X/10 or newer in an unlocked interactive desktop session. Filmora 9 and earlier are outside the target range. Tested here on Python 3.14.7; this server's OS requirements also apply when an older Filmora release supports older Windows versions.

powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1

Setup creates a local virtual environment, installs pinned direct dependencies and regenerates client snippets using the current folder. Do not copy .venv between computers; rerun setup. requirements-lock.txt records the complete tested environment. For an exact environment, install it with .\.venv\Scripts\python.exe -m pip install -r requirements-lock.txt and then install this project with -m pip install --no-deps -e ..

To use a non-default Filmora executable or custom shortcuts, copy config.example.json to config.local.json. Set executable to the actual Filmora editor EXE, or set FILMORA_EXE. FILMORA_MCP_CONFIG selects a config file; FILMORA_CAPTURE_DIR changes the captures folder. Shortcuts use names like ctrl+shift+s; see filmora_commands. Configuration is read at server startup.

Version detection uses executable product/file metadata, then adjacent installation version folders. filmora_major_version is normally null (auto); set it only for an otherwise unknown installation. Conflicts with a detected version are rejected. ui_target_overrides supplies exact names/automation IDs and control types for localized or changed layouts. See the compatibility guide for examples. Multiple installations require explicit executable/window selection.

After relocating the project, recreate its virtual environment with setup.ps1, then update registrations that still point at the previous folder:

powershell -NoProfile -ExecutionPolicy Bypass -File .\connect-clients.ps1 -RelocateFrom 'D:\Previous\FilmoraMCP' -Preview
powershell -NoProfile -ExecutionPolicy Bypass -File .\connect-clients.ps1 -RelocateFrom 'D:\Previous\FilmoraMCP'

Replace the example with the actual previous project path. Relocation updates only matching Filmora registrations, preserves other server settings, and creates backups. A conflicting command or different arguments are left for review.

Operation and limits

  • Run the server as the same Windows user and integrity level as Filmora. Keep the desktop unlocked and avoid competing mouse/keyboard input.

  • Input is scoped to validated Filmora processes. If a modal opens, list windows and select that dialog; reselect the editor when it closes.

  • Screenshot/UI observations expire after 60 seconds and are invalidated by input, window selection or changed window geometry. Get a fresh observation after every action. Manual UI changes can also stale an observation: always refresh.

  • Screenshots include the selected Filmora window. They may contain project content; save=True writes a local capture. Screenshot images are sent to the requesting MCP client. Default mode="visible" captures displayed pixels; activate/reveal Filmora first. This refuses capture when another app is foreground. Optional mode="window" uses native window capture while obscured, but may show stale GPU surfaces.

  • To stop input, move the mouse to desktop (0,0) or create an empty PAUSE file in this folder. Remove the file/move the pointer to resume. Restarting the server is unnecessary.

  • A successful input tool means dispatched, not a verified edit. Inspect selection, playhead, dialog and output before claiming completion. Pixel operations cannot promise frame-exact editing without visual verification.

  • Native file-dialog helper requires an unambiguous standard filename field. For Filmora custom dialogs, inspect and edit explicit controls instead. The helper refuses an existing Save As destination; ordinary Save commands and explicit UI interactions can still modify existing projects.

  • Input does not work from a headless service or locked desktop. Accessibility may be incomplete for Qt canvas items; use screenshots. Capture may fail/appear blank with particular GPU/window states; activate and restore Filmora before retrying. Display scaling and external dialogs require fresh observations.

  • The server uses stdio only, opens no listening network port, and has no arbitrary shell/code-execution tool. It does not automate authentication or automatically dismiss save/overwrite/license prompts. General UI controls can still start recording, rendering or online features when instructed; inspect the visible state first.

Verification

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts\smoke_test.py --report logs\smoke-test.json

The first command includes protocol, compatibility, client-registration and input-guard tests. The second requires Filmora to be open and checks real MCP status, native screenshots and exposed accessible controls without editing the current project. Use --no-desktop for protocol-only checks. See docs/VALIDATION.md for actual run results and untested workflows.

Documentation

Sources

MIT licensed. Wondershare and Filmora are trademarks of their respective owners.

Available Tools

33 tools
filmora_activateA
Destructive

Restore/foreground the selected Filmora window. Does not maximize or resize it.

Inputs: no named parameters.

filmora_capabilitiesC
Read-only

Resolve commands/features for detected Filmora X/10+; probe_ui checks exposed controls, not account entitlements.

Inputs: probe_ui.

filmora_clickB
Destructive

Click screenshot pixels. Double-click count=2; Alt-click adds a keyframe where supported.

Inputs: x (required), y (required), observation_id (required), count, +2 more.

filmora_clip_panelB
Destructive

Open a selected clip's editing panel. Inspect and adjust actual controls with ui_action/pixels.

Inputs: panel (required).

filmora_commandB
Destructive

Dispatch a named command from filmora_commands. Focus/selection determines its effect; verify afterward.

Inputs: action (required), repeat.

filmora_commandsC
Read-only

Find version-resolved shortcuts. Unavailable/ambiguous commands are omitted unless requested.

Inputs: group, query, include_unavailable.

filmora_dragB
Destructive

Drag clips/assets/trim handles/keyframes using fresh screenshot pixels. Alt-drag can replace media.

Inputs: end_x (required), end_y (required), start_x (required), start_y (required), +3 more.

filmora_editB
Destructive

Edit selected timeline clips; inspect selection and playhead first, then verify the result.

Inputs: action (required), repeat.

filmora_feature_guideB
Read-only

Get a UI route for an advanced feature. Guidance is not an executed edit or guaranteed availability.

Inputs: feature (required).

filmora_fill_file_dialogA
Destructive

Fill an observed native file chooser (no shell). Default leaves it open for inspection.

paths are absolute local paths. Existing files required for Open/Import; Save As requires a new filename. Select the actual dialog via filmora_select_window first. Custom Qt dialogs need explicit UI actions.

Inputs: paths (required), submit, save_as.

filmora_import_media_dialogA
Destructive

Open the import chooser; list/select its window before filling paths.

Inputs: no named parameters.

filmora_inspectB
Read-only

Read UI Automation controls and focus. IDs expire; query filters returned names, not tree traversal.

Inputs: hwnd, query, max_depth, max_elements.

filmora_keyA
Destructive

Dispatch one key/chord, e.g. ctrl+b, escape, tab, left. No raw script or Windows key support.

Inputs: chord (required), repeat.

filmora_launchA
Destructive

Launch installed Filmora if it is not running; does not open or replace a project.

Inputs: no named parameters.

filmora_markerC
Destructive

Add/edit marker, assign color mark, or control in/out range in the focused timeline/player.

Inputs: action.

filmora_new_projectA
Destructive

Open new-project workflow. Existing project may prompt to save; inspect before proceeding.

Inputs: no named parameters.

filmora_open_exportA
Destructive

Open export settings; inspect/set real fields. Does not start rendering, upload, or bypass license dialogs.

Inputs: no named parameters.

filmora_open_panelB
Destructive

Open a Filmora X/10+ panel using live controls, exact-label selectors, or a version-resolved shortcut.

Includes toolbar toggles such as auto_snap and auto_ripple: these toggle state, not ensure enabled. Configure ui_target_overrides for localized/different layouts. Disabled/ambiguous controls never trigger fallbacks.

Inputs: panel (required).

filmora_open_project_dialogB
Destructive

Open Filmora's project chooser. List/select the dialog, then fill_file_dialog with an existing .wfp.

Inputs: no named parameters.

filmora_playbackB
Destructive

Playback/navigation shortcuts. Focus the timeline/player before navigation.

Inputs: action (required), repeat.

filmora_save_projectA
Destructive

Save project or open Save As. Inspect dialogs; use a new filename to preserve the original.

Inputs: save_as.

filmora_screenshotA
Read-only

Return actual MCP PNG image + coordinate metadata. Optional crop uses original window pixels.

Click/drag/scroll coordinates use displayed image pixels, including resize/crop mapping. save=True stores a uniquely named PNG in captures. Restore minimized windows first. window mode captures the app even when obscured, but GPU previews may have artifacts. visible mode captures displayed pixels; Filmora must be foreground and unobscured.

Inputs: crop, hwnd, mode, save, +1 more.

filmora_scrollB
Destructive

Scroll a pane at screenshot pixels. Positive ticks scroll up/right; negative down/left.

Inputs: x (required), y (required), ticks (required), observation_id (required), +2 more.

filmora_select_windowB
Destructive

Select a handle returned by filmora_windows. Select modal dialogs explicitly.

Inputs: hwnd (required).

filmora_snapshot_frameA
Destructive

Ask Filmora to save a source/player frame via its Snapshot command (different from UI screenshot).

Inputs: no named parameters.

filmora_stateC
Read-only

Return a screenshot plus accessible controls, each with its own observation ID.

Inputs: max_width, max_elements.

filmora_statusA
Read-only

Read installed executables, running Filmora windows, pause state and server version.

Inputs: no named parameters.

filmora_type_textB
Destructive

Insert literal Unicode into a focused observed Edit/Document control. Reinspect after focusing first.

Inputs: text (required), element_id (required), observation_id (required).

filmora_ui_actionB
Destructive

Operate one freshly inspected control. set_value sets text; set_range uses a slider's native numeric range.

select chooses a combo/list item by exact visible text. Unsupported accessibility patterns raise an error; capture a screenshot and use pixels instead. Value parameter is a string, including numeric ranges.

Inputs: element_id (required), observation_id (required), value, action.

filmora_verify_outputA
Read-only

Check a specific exported local file's size/timestamps; does not assert codec/content validity.

Inputs: path (required), minimum_bytes.

filmora_waitA
Read-only

Bounded wait for UI/render changes; follow with screenshot or inspection.

Inputs: seconds.

filmora_windowsA
Read-only

List visible Filmora windows/dialogs by validated process, with handles and geometry.

Inputs: no named parameters. Returns: result

filmora_zoomC
Destructive

Zoom timeline using Filmora's default shortcuts.

Inputs: direction (required), repeat.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.2/5.0

    Scored across 33 tools

    Disambiguation3/5

    The set mixes high-level Filmora actions (edit, zoom, playback) with low-level UI primitives (ui_action, click, type_text, key), creating overlap in how an agent might accomplish the same task. Descriptions provide guidance, but the hierarchy is complex, so an agent must carefully distinguish when to use a control-oriented tool versus a pixel-oriented one.

    Naming Consistency4/5

    All tools use the filmora_ prefix and snake_case, which is consistent. However, the verb/noun pattern is not uniform: some are verb_noun (open_panel, save_project), some noun-only (status, windows, screenshot), and some noun_noun (feature_guide, clip_panel), though still readable.

    Tool Count2/5

    With 33 tools, the surface is heavy for the domain and exceeds the threshold where each tool clearly earns its place. Several tools could be consolidated (e.g., inspect/state, ui_action/click/type_text/key, commands/command), and high-level wrappers duplicate low-level primitives.

    Completeness4/5

    The set covers app lifecycle, project/media/export management, editing, and a full UI automation layer. Minor gaps exist for explicit quit/close, undo/redo, and direct render start, but agents can work around these using existing key commands or tools.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • openowl

      mihir-kanzariya
      A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that gives any AI assistant eyes and hands on your desktop — screenshots, clicking, typing, OCR, window management, accessibility-tree queries, workflow recording.
      5
      Apache 2.0

    • umbriel

      ObscuritySRL
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for driving any Windows app through five layers including OCR, UI Automation, and direct OS operations. Enables AI agents to control Windows desktop and OS cursor-free, even on background/locked windows.
      67 npm
      3
      MIT

    • winauto-mcp

      PingPong2534
      F
      license
      Not graded
      quality
      B
      maintenance
      MCP server that lets an LLM see and drive any running Windows app: attach a window, screenshot it, read its UI Automation tree, and send clicks, typed text, and key presses with pixel coordinates.
      -