Fdx Server

Description

fdx-mcp-server is a Model Context Protocol (MCP) server that lets AI agents read, analyze, and manipulate Final Draft screenplay files (.fdx). It exposes tools for parsing scene headings, character arcs, dual dialogues, SmartType dictionaries, pagination maps, script breakdowns, and more — effectively giving an LLM the ability to understand and edit screenplay structure.

Written in TypeScript, it runs on Bun or Deno using the stdio transport protocol, making it suitable for integration with any MCP-compatible client such as Claude Desktop.

Repository: github.com/dmongrel/fdx-mcp-server · Changelog: CHANGELOG.md

---

Table of Contents

• Installation
  • Prerequisites: Node.js
  • Option A — Direct from GitHub (Bun or Deno)
  • Option B — Global NPM Install
• Usage
• Features
• Publishing

---

Installation

Prerequisites: Node.js

Node.js is required for Option B (Global NPM Install). If you plan to use that option, install it first using one of these methods:

• Windows / macOS: Download the LTS installer from nodejs.org and run it.
• Linux (apt): curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
• Homebrew (macOS / Linux): brew install node

Verify the installation by running node --version and npm --version in your terminal.

Option A — Direct from GitHub (Bun or Deno)

If you have Bun, Deno, or both installed, you can run the server directly from raw.githubusercontent.com without installing it locally. No compilation or OS code-signing warnings needed.

⚠️ Rate-limit notice: This path fetches the server from raw.githubusercontent.com every time your MCP client starts. GitHub enforces an anonymous usage policy that limits unauthenticated requests to 60 per hour (across all of github.com and its subdomains). If you exceed this limit, requests will be rejected with a 403 Forbidden error until the window resets. Frequent restarts can trigger this — for heavy use, see Option B which caches everything locally.

Option B — Global NPM Install

If you prefer a traditional Node.js/NPM setup, install the package globally from the npm registry. This downloads all dependencies locally so the server boots instantly and works 100% offline.

npm install -g fdx-mcp-server

To update later: npm update -g fdx-mcp-server

Because this installs a pre-built package from the registry (rather than cloning and building the repo locally), it avoids the Windows npm/node-tar ENOENT race that git-based (github:user/repo) installs are prone to.

---

Usage

Add a configuration block to your MCP client's config file (e.g., claude_desktop_config.json or .mcp.json). Select the entries that apply to you:

Using Bun only:

{
  "mcpServers": {
    "fdx-mcp-server-bun": {
      "command": "bun",
      "args": ["run", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    }
  }
}

Using Deno only:

{
  "mcpServers": {
    "fdx-mcp-server-deno": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-read", "--allow-write", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    }
  }
}

Using both Bun and Deno:

{
  "mcpServers": {
    "fdx-mcp-server-bun": {
      "command": "bun",
      "args": ["run", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    },
    "fdx-mcp-server-deno": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-read", "--allow-write", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    }
  }
}

Using global NPM install:

{
  "mcpServers": {
    "fdx-mcp-server": {
      "command": "fdx-mcp-server",
      "args": []
    }
  }
}

---

Features

Key capabilities exposed by fdx-mcp-server:

• Document lifecycle — open, save, reload, create new .fdx files; manage server-side document cache.
• Batch edits & savepoints — apply an ordered list of edits atomically (all-or-nothing, with automatic rollback on failure), or take a manual savepoint around any sequence of edits and roll back to it on demand.
• Document integrity — detect and repair paragraphs that silently share a duplicated id (a FinalDraft copy/paste artifact that otherwise makes id-addressed edits land on the wrong paragraph); list every proofing-flag (spellcheck squiggle) hit with get_flagged_words, or just its count via get_script_stats, to confirm a sweep didn't alter anything; list or exclude drafting placeholders ([FIX - ...]-style whole-bracket paragraphs) with get_placeholders and get_script_stats's excludePlaceholders, so a paragraph-count baseline stays usable while they're still in the document.
• Scene analysis — parse scene headings (INT./EXT., location, time of day), extract scene index and properties, compute script stats and page maps; set a scene's Color and/or Title with edit_scene_properties, or color a newly created Scene Heading in the same call via edit_par action=create's color parameter.
• Character tracking — retrieve character lists, extension metadata (V.O., O.S.), per-character scene appearance counts, and arc beats across scenes; rename or merge a character across every place its name is stored (cue paragraphs, dictionary, cast, arc beats, highlighting) in one call; create a new Character/[Parenthetical]/Dialogue speech as one atomic insertion.
• Dual dialogue support — read and create side-by-side dialogue blocks.
• SmartType dictionaries — manage the FinalDraft autocomplete lists: characters, extensions, transitions, scene intros, times of day, spell-check lists, and paragraph types.
• Location usage — see actual location usage parsed from Scene Heading text (not just the autocomplete dictionary) and rename a location across every scene that uses it in one call.
• Formatting & styling — query and edit element settings (fonts, indentation, spacing) for every paragraph type; manage header/footer content.
• Title page management — read and write title, author, contact block, copyright, and based-on credits.
• Script breakdowns — generate full production breakdown reports (props, vehicles, camera, cast) as text or HTML/PDF.
• Macro system — query macro aliases and their activation scopes.
• Search & navigation — find paragraphs by text, list sections and section contents, retrieve revision colors and display board data; diff two documents' paragraphs by id (added/removed/modified) — useful for confirming what a versioned save actually changed.

---

Publishing

Maintainer notes for releasing a new version to npm:

bun run build     # rebuilds dist/index.js, which is checked into the repo
npm publish

If the npm account has two-factor authentication enabled, each npm publish requires its own live 2FA approval — logging in beforehand is not enough, and the approval from one publish does not carry over to the next. Because of this, npm publish has to be run interactively, in a real terminal, by whoever holds the authenticator — it cannot be scripted or run non-interactively (e.g. from an AI coding assistant's shell tool) without a fresh prompt failing with an EOTP error.