Command line and AI agents

MarkupRight can work without its window. Scripts and scheduled jobs use the markupright command, and AI assistants use the same capabilities through the MCP connector: hundreds of tools for reading, marking up and measuring PDFs.

Expert·12 minute read

Command line

markupright (on Windows terminals, markupright-cli)

AI assistants

MarkupRight ▸ Preferences ▸ Admin ▸ MCP

You'll need

A licence or the trial. Viewer mode refuses batch jobs and the connector.

Where the program is

The command-line program is the MarkupRight app itself:

Commands

Exit codes

# macOS: check an installation from Terminal
/Applications/MarkupRight.app/Contents/MacOS/markupright --version
/Applications/MarkupRight.app/Contents/MacOS/markupright --selftest

# Windows: the same checks from PowerShell
& "$env:LOCALAPPDATA\MarkupRight\markupright-cli.exe" --version
& "$env:LOCALAPPDATA\MarkupRight\markupright-cli.exe" --license-status

Batch jobs from the command line

Every job on the Batch menu can run from a script, for example overnight on a server. You give it a file list (a .bcx file, the same kind the Batch dialogs save with Save…) and the job's options.

<?xml version="1.0" encoding="UTF-8"?>
<markupright-batch version="1">
  <file path="A-101 Level 1 Floor Plan.pdf" pages="all"/>
  <file path="A-102 Level 2 Floor Plan.pdf" pages="1"/>
</markupright-batch>

The pages of each file are all, current, even, odd, landscape, portrait, or page numbers such as 1,3,5. Then:

# Stamp the top right corner of every listed page
markupright batch stamp --bcx issue.bcx --stamp "Approved.pdf" --anchor top_right

# Make scanned pages searchable
markupright batch ocr --bcx scans.bcx --language en

# Protect every file with a saved security preset (passwords only from the environment)
export ISSUE_MASTER_PW='…'
markupright batch security --bcx issue.bcx --preset "Issue for Construction" --master-password-env ISSUE_MASTER_PW

# Slip-sheet a new issue into the current set, carrying the markups over
markupright batch slip-sheet --bcx paired.bcx --replace --copy-markups

Each file prints one line saying what happened. A mistake in the command prints the full list of features and options, with exit code 2.

Connect an AI assistant (MCP)

The Model Context Protocol (MCP) is an open standard that lets an AI assistant, such as Claude, use tools on your computer. MarkupRight's MCP connector gives an assistant the same abilities you have in the app, as tools it can call: open a PDF, read its text, add markups, measure, compare, run batch jobs, build Sets and more. You ask in plain language ("cloud every room on A-101 that's under 100 sq ft") and the assistant does the steps.

The connector is off until someone turns it on.

The configuration looks like this. Adding --root confines the assistant to one folder's files, which we recommend:

{
  "mcpServers": {
    "markupright": {
      "command": "/Applications/MarkupRight.app/Contents/MacOS/markupright",
      "args": ["mcp", "--root", "/Users/priya/Projects/Harbor St Clinic"]
    }
  }
}

On Windows the command is the path of markupright.exe, written with doubled backslashes: "C:\\Users\\priya\\AppData\\Local\\MarkupRight\\markupright.exe".

What an assistant can and can't do

• It works on copies in memory. Opening a document gives the assistant its own working copy. Nothing changes on disk until it saves (doc_save), and every change can be undone (edit_undo). If it saves a file you have open, MarkupRight reloads it.
• It stays inside its folder. With --root, any path outside that folder is refused.
• It respects locks and security. Locked markups are refused or skipped, and a document's passwords, permissions and signatures apply to the assistant just as they do to you.
• It needs a licence. The connector refuses to start in viewer mode. The Collab tools need a Team licence.
• It doesn't use the network. The assistant talks to MarkupRight through the program's input and output; no network port is opened.

Things to ask

• "Open A-101 Level 1 Floor Plan.pdf and list the open RFIs with their authors."
• "Set the scale of every page in M-101.pdf to 1/8 inch = 1 foot and give me the area of each room."
• "Compare issue1.pdf with issue2.pdf and summarise what changed on each sheet."
• "Stamp every PDF in the For Construction folder with the Approved stamp, top right."
• "Export a CSV of all markups that aren't Completed."

The tools at a glance

The connector offers about 335 tools, plus 25 Collab tools with a Team licence. The assistant reads their descriptions itself; this table helps you know what to ask for.

# Minimal MCP client: list the tools MarkupRight offers
import json, subprocess
p = subprocess.Popen(["markupright", "mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
def rpc(i, method, params=None):
    p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": method, "params": params or {}}) + "\n")
    p.stdin.flush()
    return json.loads(p.stdout.readline())
rpc(1, "initialize", {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "demo", "version": "1"}})
p.stdin.write(json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + "\n"); p.stdin.flush()
print(len(rpc(2, "tools/list")["result"]["tools"]), "tools")