PixInsight Connector

What PixInsight Connector does

PixInsight Connector exposes roughly 80 PixInsight operations as MCP tools. Its scope covers image sessions, process execution, channels, tone and detail work, masks, stars, narrowband workflows, astrometry, measurements, previews, introspection, and PJSR execution.

The connector is a toolbox rather than a preset workflow. Tools accept the values that control an operation and return measurements or process results; they do not decide which steps make a good image or prescribe an ordering. Technique can be supplied separately through skills stored in an agent's repositories.

Operations include opening, closing, cloning, restoring, renaming, cropping, exporting, and inspecting images. Agents can align images, combine channels, run AutomaticBackgroundExtractor per channel, apply LRGB combination, compare views, enhance detail, execute PixelMath, and invoke PixInsight processes by constructor name. Astrometry tools support offline plate solving against local Gaia data, WCS copying, catalogue searches, and solution verification.

How it works

An MCP client starts the connector through the pixinsight-connector command. On the first tool call, the connector starts PixInsight and its watcher script, then communicates with the application through a local file bridge. The server returns view IDs, numerical measurements, console output, file paths, and process results as appropriate.

Working files are restricted to the selected workspace's agentic/ and output/ folders. A workspace can be selected by a session tool or by the PIXINSIGHT_CONNECTOR_WORKSPACE environment variable; otherwise the connector uses the folder in which the harness started. Temporary images and scratch data are kept under the agentic area, while exported and generated output files are constrained to approved locations.

The PJSR tools run JavaScript using PixInsight's V8 engine. Inline snippets and source files are parsed before execution, and the connector returns PixInsight console output. The generic process tool can instantiate installed PixInsight processes, validate parameter names, and run them on a view or globally.

Setup and configuration

Install Node.js 22 or newer and PixInsight 1.9.5 or newer, then install the connector globally:

npm install -g pixinsight-connector

Register pixinsight-connector as an MCP server in the client. For clients using an mcpServers configuration, the entry is:

{
  "mcpServers": {
    "pixinsight": {
      "command": "pixinsight-connector"
    }
  }
}

Claude Code can register it with claude mcp add -s user pixinsight -- pixinsight-connector. The doctor command checks the local setup:

pixinsight-connector doctor

Use npx -y pixinsight-connector instead of a global installation when appropriate. PIXINSIGHT_BIN overrides the PixInsight executable, and PIXINSIGHT_DIR overrides its installation root. Packs can be loaded through PIXINSIGHT_CONNECTOR_PACKS; packs are arbitrary code and run with the user's privileges.

Tools and capabilities

• Manage open views, including listing, renaming, cloning, restoring, cropping, dimension checks, statistics, and export.
• Apply StarAlignment, channel combination, ABE, LRGB combination, PixelMath, LocalHistogramEqualization, HDR multiscale processing, and protected detail enhancement.
• Plate solve images, copy WCS data, verify astrometric accuracy, and query local Gaia catalogues.
• Compare images numerically, including absolute differences, percentiles, range violations, and identity checks.
• Inspect installed PixInsight processes, scripts, Gaia databases, MARS files, system resources, and XTerminator process banners.
• Run arbitrary installed processes, PJSR snippets, and PJSR files when dedicated tools are not sufficient.

Limitations and notes

PixInsight Connector is a community project and is not affiliated with or endorsed by Pleiades Astrophoto. The image-processing tools do not supply a complete pipeline or quality verdict. Plate solving requires suitable position and scale information unless the image keywords provide it, and astrometric verification requires a solved view. PixelMath expressions use PixInsight-specific channel syntax and do not support pow() in these tools.

File access is deliberately limited to the workspace output and state locations. Export formats can discard metadata that the format cannot store. Cropping removes an image's astrometric solution because that is PixInsight behavior. The connector supports macOS, Windows, and Linux, with platform-specific executable discovery handled by the connector.