FreeFlyer MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
FreeFlyer MCP
Connect an MCP-compatible assistant to a locally licensed copy of a.i. solutions FreeFlyer for script execution, mission-plan runs, orbit propagation, and ground-station access analysis.
The bridge uses temporary files and native command-line execution through Python's subprocess.run(). It requires no FreeFlyer Runtime API package. A licensed FreeFlyer installation is required separately; this repository contains no proprietary executables, data files, or licenses.
Features
Four stdio MCP tools:
run_freeflyer_script,run_mission_plan,propagate_orbit, andcalculate_access_times.A fresh temporary workspace for every run, with serialized execution per server instance.
Captured stdout/stderr, generated reports, explicit execution timeouts, and process-tree termination.
Windows
ff.exeand macOSff-clisupport through an explicit executable path.Structured JSON telemetry and pass events from generated CSV reports.
Related MCP server: astrodynamics-mcp
Requirements
Python 3.10 or later; Python 3.11 or 3.12 is recommended.
FreeFlyer installed and licensed for the account that launches the MCP client.
A FreeFlyer command-line executable supporting
-mpand-tmps.An MCP client such as Codex, Claude Desktop, or Cursor.
A raw report script and a short TwoBody propagation have been exercised end to end on FreeFlyer 8.0.1 for macOS with an Engineer license. Windows process-tree cleanup has unit coverage but still requires validation on a licensed Windows host. The access tool uses approximate one-second sampling; see modeling limits.
Installation
Clone this repository on the computer with FreeFlyer installed:
git clone https://github.com/Sammy-Sekhon/freeflyer-mcp.git
cd freeflyer-mcpmacOS
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
export FREEFLYER_EXE_PATH='/Applications/FreeFlyer 8.0.1.76638900.app/Contents/Resources/bin/ff-cli'
export FREEFLYER_CLI_MODE=documented
.venv/bin/python smoke_test.py --with-freeflyerReplace the versioned application path with your installed version. The executable is inside the application bundle; a Windows-style bin/ff.exe path will not work on macOS.
Windows (PowerShell)
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
$env:FREEFLYER_EXE_PATH = 'C:\Program Files\a.i. solutions\FreeFlyer 7.10\bin\ff.exe'
$env:FREEFLYER_CLI_MODE = 'documented'
.\.venv\Scripts\python.exe smoke_test.py --with-freeflyerReplace the example with your actual executable. Newer versions may name the native executable differently; use the CLI executable shipped with your installation and verify its --help output.
To run the server manually:
# macOS
.venv/bin/python server.py# Windows
.\.venv\Scripts\python.exe server.pyA stdio server waits for MCP messages and may show no output. It is not a web service and does not expose an HTTP port. Stop a manual instance before having your MCP client launch another one.
Configure your MCP client
Use absolute paths to the virtual environment's Python interpreter and server.py. Put environment variables directly in the client configuration: desktop applications may not inherit values exported in a terminal.
Codex
Merge the following tables into ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml). Substitute your paths. This example is for macOS:
[mcp_servers.freeflyer]
command = "/absolute/path/freeflyer-mcp/.venv/bin/python"
args = ["/absolute/path/freeflyer-mcp/server.py"]
cwd = "/absolute/path/freeflyer-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 3700
[mcp_servers.freeflyer.env]
FREEFLYER_EXE_PATH = "/Applications/FreeFlyer 8.0.1.76638900.app/Contents/Resources/bin/ff-cli"
FREEFLYER_CLI_MODE = "documented"For Windows, use TOML literal strings for backslash paths:
[mcp_servers.freeflyer]
command = 'C:\tools\freeflyer-mcp\.venv\Scripts\python.exe'
args = ['C:\tools\freeflyer-mcp\server.py']
cwd = 'C:\tools\freeflyer-mcp'
startup_timeout_sec = 20
tool_timeout_sec = 3700
[mcp_servers.freeflyer.env]
FREEFLYER_EXE_PATH = 'C:\Program Files\a.i. solutions\FreeFlyer 7.10\bin\ff.exe'
FREEFLYER_CLI_MODE = 'documented'Choose one platform's configuration, not both. Reload MCP servers or restart the application after saving. codex mcp get freeflyer checks registration; smoke_test.py checks actual protocol startup. The client timeout is slightly longer than the server's maximum 3,600-second run timeout to allow cleanup and report collection.
Claude Desktop and Cursor
Both use a top-level mcpServers JSON object. Merge this macOS example into the appropriate file:
{
"mcpServers": {
"freeflyer": {
"command": "/absolute/path/freeflyer-mcp/.venv/bin/python",
"args": ["/absolute/path/freeflyer-mcp/server.py"],
"env": {
"FREEFLYER_EXE_PATH": "/Applications/FreeFlyer 8.0.1.76638900.app/Contents/Resources/bin/ff-cli",
"FREEFLYER_CLI_MODE": "documented"
}
}
}
}For Windows, use these path forms inside the same JSON structure:
{
"mcpServers": {
"freeflyer": {
"command": "C:\\tools\\freeflyer-mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\tools\\freeflyer-mcp\\server.py"],
"env": {
"FREEFLYER_EXE_PATH": "C:\\Program Files\\a.i. solutions\\FreeFlyer 7.10\\bin\\ff.exe",
"FREEFLYER_CLI_MODE": "documented"
}
}
}
}Client | Configuration location |
Claude Desktop, macOS |
|
Claude Desktop, Windows |
|
Cursor, project |
|
Cursor, global |
|
Restart or reload the client after saving and verify that four tools appear. A client's own tool timeout may need adjustment for long runs. See the local MCP client guide and Cursor MCP documentation.
Use the tools
After connecting, ask your assistant to use a specific tool. For example: “Use FreeFlyer to propagate an Earth orbit with a 7,000 km semimajor axis for one hour, sampled every 60 seconds.”
run_freeflyer_script
Parameters: script_content (string), timeout_seconds (integer, default 60; range 1–3,600).
{
"script_content": "Report \"Hello from FreeFlyer\" to MCPReport;",
"timeout_seconds": 60
}The server declares ReportInterface MCPReport("output.csv") for you. Explicitly report values to MCPReport or create your own report file. The server wraps the script in a standalone text Mission Plan interpreted with -tmps; it does not fabricate an XML schema.
The result contains ok, returncode when available, stdout, stderr, truncation flags, the executed command, and generated files. For example, files["output.csv"]["text"] contains the report text. UI objects and visualization commands in raw scripts are rejected.
run_mission_plan
Parameters: mission_plan_path (absolute path), switches (optional string list), timeout_seconds (default 120; range 1–3,600).
{
"mission_plan_path": "C:\\missions\\analysis.MissionPlan",
"timeout_seconds": 120
}The plan is copied into its own workspace and executed headlessly. Dependencies must be self-contained or use absolute paths. Use relative output filenames so results are created in the run directory and collected. Existing XML plans are not rewritten or stripped of UI components; prepare them for headless execution first.
For plan inputs, switches currently accepts pairs of -ni or --namelist-input followed by a namelist path. Prefer absolute namelist paths. Other switches are rejected to avoid changing the selected plan, UI behavior, or license state.
propagate_orbit
{
"epoch": "Jan 01 2026 00:00:00.000",
"sma": 7000,
"ecc": 0.001,
"inc": 51.6,
"raan": 0,
"arg_perigee": 0,
"true_anomaly": 0,
"duration_hours": 1,
"step_size_seconds": 60
}Epochs are UTC, semimajor axis is in km, angles are in degrees, duration is in hours, and the sampling step is in seconds. The tool returns an array of Epoch, X, Y, Z, Vx, Vy, Vz objects in Earth-centered ICRF, km, and km/s. It includes the initial epoch and exact end epoch, shortening the final step if needed. Execution timeout: 120 seconds; maximum output: 100,000 samples.
calculate_access_times
Parameters: tle_line1, tle_line2, ground_station_lat, ground_station_lon, ground_station_alt, start_time, and duration_days.
Supply two matching, checksum-valid, exactly 69-character TLE lines. Latitude and east longitude are degrees; altitude is km; the start date uses the same UTC calendar format as propagation. Use TLEs appropriate to the requested date. Maximum analysis duration is seven days; execution timeout is 120 seconds.
The tool returns a list of pass events:
[
{
"AOS": "Jan 01 2026 12:00:00.000000000",
"LOS": "Jan 01 2026 12:08:00.000000000",
"duration_seconds": 480,
"max_elevation_deg": 42.5,
"clipped_start": false,
"clipped_end": false,
"sample_seconds": 1
}
]This is an illustrative result, not a computed pass prediction. An empty array means the generated report was valid but contained no passes; a missing or malformed report is an error.
Executable discovery and command modes
Discovery checks, in order:
FREEFLYER_EXE_PATH— an explicit absolute path; invalid values produce an error.FREEFLYER_64_INSTALL_DIRECTORY/bin/ff.exe.Windows
C:\Program Files\a.i. solutions\FreeFlyer *\bin\ff.exe, including the oldera.i. solutions, Incdirectory, choosing the highest numeric version.
On macOS, set the explicit path to the installed application's Contents/Resources/bin/ff-cli; automatic application-bundle discovery is not implemented.
Set FREEFLYER_CLI_MODE=documented for standard installations. This produces ff.exe -mp <plan> or ff-cli -mp <plan>, with -tmps added for raw scripts. The CLI supplies headless execution.
For compatibility with custom installations, FREEFLYER_CLI_MODE=requested produces -m <plan> -headless. This is the current fallback when the variable is omitted, but those flags are not supported by the standard CLI version tested. Always set documented as shown above. There is no automatic retry that could execute a plan twice.
Vendor references: command-line execution, script interpretation, and ReportInterface.
Modeling limits
Propagation uses Earth-centered TwoBody dynamics for elliptic orbits. It does not include drag, nonspherical gravity, third-body forces, or maneuvers.
Access uses SGP4 and geometric elevation at or above zero degrees, sampled every second. AOS/LOS are sample times, maximum elevation is a sampled lower bound, and subsecond grazing passes can be missed.
Passes crossing an analysis boundary are clipped and flagged. Terrain, refraction, and antenna masks are not modeled.
Generated scripts target nanosecond timing mode. Older millisecond-only installations require adaptation.
These tools support analysis workflows; validate results against a trusted reference before operational use.
Execution and file handling
Each run owns a TemporaryDirectory. The server copies inputs there, sets it as the working directory, collects up to 100 files / 8 MiB of text, and cleans it up. Truncated analysis CSV is an error rather than partial telemetry. Absolute output paths are outside this collection. Binary results are not supported.
A dedicated Python supervisor invokes FreeFlyer with subprocess.run(..., timeout=...). The parent's shorter watchdog terminates the supervisor's process tree on timeout: taskkill /F /T /PID <supervisor_pid> on Windows, or an isolated process group on macOS/Linux. This avoids relying on a nonexistent TimeoutExpired.pid. Cleanup diagnostics and partial logs are returned. Host crashes or forced termination of the MCP application are outside the watchdog's guarantee.
Runs are serialized within one server instance. Multiple clients or server instances can consume multiple license seats. Logs are spooled to disk, so verbose runs may use disk space until completion or timeout.
Only execute trusted scripts and plans: workspace isolation prevents filename collisions but is not an operating-system sandbox. FreeFlyer scripts can access files and launch programs with the account's permissions. Do not expose this local bridge to untrusted clients.
Tests and troubleshooting
From the repository directory, with dependencies installed:
# macOS/Linux
.venv/bin/python -m unittest -v test_server
.venv/bin/python smoke_test.py
.venv/bin/python smoke_test.py --with-freeflyer# Windows
.\.venv\Scripts\python.exe -m unittest -v test_server
.\.venv\Scripts\python.exe smoke_test.py
.\.venv\Scripts\python.exe smoke_test.py --with-freeflyerThe unit suite and default smoke test need no FreeFlyer installation. The optional licensed smoke test runs a short report script using the configured executable. Unit tests cover subprocess success/failure, timeout termination, discovery, command construction, CSV validation, temporary workspace cleanup, and MCP schemas. They do not certify astrodynamics accuracy.
Symptom | Check |
Tools do not appear | Use the venv's Python, verify |
Executable path error | Use an absolute path. On macOS, use |
Unknown command-line flag | Set |
License failure | Confirm FreeFlyer works under the same user account and that a seat is available. |
Client times out first | Increase the client's MCP tool timeout above the requested execution timeout. |
Empty/missing output | Report explicitly to |
Plan fails after copying | Use absolute dependency paths and remove GUI-only behavior. |
For new FreeFlyer/platform combinations, validate a short report, a known orbit case, an access case, and a deliberate timeout. Confirm the owned processes exit and the seat is released. When reporting bugs, include platform, Python/FreeFlyer versions, and a minimal script; redact license information, credentials, local paths, and proprietary mission data.
License
This bridge is released under the MIT License. FreeFlyer is a product of a.i. solutions and requires its own license. This is an independent community project and is not affiliated with or endorsed by a.i. solutions.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Set up and run your firm's Precision AI agents, skills and routines from any MCP client.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Official MCP bridge to Exogram—the Personal AI Agent for your work, people, and life.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables Large Language Models or other MCP clients to interact with Ansys/AGI STK (Systems Tool Kit), allowing users to control STK Desktop simulations programmatically or via natural language.43-
- AlicenseNot gradedqualityBmaintenanceAn MCP server that equips LLM clients with authoritative astrodynamics tools including TLE/SGP4 propagation, Lambert solving, ground-station access, time-scale and coordinate-frame conversions, and more.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients like Codex to control Ansys Workbench and ICEM CFD locally, executing scripts, managing projects, and running simulations.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables an AI assistant to invoke local file operations, multi-engine web search, weather, system commands, developer utilities, and code execution over MCP, and includes a web dashboard for managing endpoints, testing tools, and viewing live logs.65 npm1MIT