Integrations
MCP access
Terminalis provides read-only MCP access for a local client to inspect terminal metadata and recent output. Keep the app running while the client uses it.
Connect a client
The terminalis-mcp package is a Node stdio server and requires Node.js 18 or later available on the client's PATH. Add an entry using your MCP client's server configuration format; clients using an mcpServers object can use:
{
"mcpServers": {
"terminalis-mcp": {
"command": "npx",
"args": ["-y", "terminalis-mcp"]
}
}
}
Restart or reconnect the client after saving. It launches the wrapper, which discovers the running app through the local mcp-port file. If the app was started with a custom TERMINALIS_CONFIG_DIR, give the server entry the same env value so it finds that configuration instance:
"env": { "TERMINALIS_CONFIG_DIR": "/absolute/path/to/terminalis-config" }
The example is a property inside the server entry, not a separate configuration file. Do not point an MCP client directly at the internal HTTP port as though it were an MCP-over-HTTP endpoint.
Enable access
Open Settings → AI → MCP access and enable MCP terminal access. It is on by default. Turning it off immediately blocks metadata and output reads; reconnecting or restarting the app is not necessary for the setting itself.
The setting controls all terminals exposed through this surface. It does not choose individual profiles. Resetting preferences restores the enabled default.
Tools and resources
| Operation | Result |
|---|---|
list_terminals | Profile metadata for available terminals. |
get_terminal_output with id and optional bytes | Recent output for one terminal, with ANSI/control sequences stripped. |
terminal://<id> resource | That terminal's metadata and recent output together. |
Output defaults to the most recent 16 KiB and is capped by the 256 KiB live session buffer. A known terminal without a session can return empty output; an unknown ID returns an error. This live buffer is distinct from the UI's persisted scrollback and does not provide complete historical logs.
Exposed data
Metadata includes id, displayName, configured cwd, profile env, local tags, status, and lastExitCode. The environment contains decoded authored profile values, including values marked Hide. The directory is the profile configuration, not a live-shell directory query.
Metadata omits attached commands, the global library, and internal startup/managed-run fields. Its status is the backend managed-session status and is not the full five-color sidebar model. Manual activity need not appear as running there.
Output is not redacted. Values printed by programs, including inherited or command-specific values absent from metadata, can still appear in returned text. Enable access only for clients you intend to let read this data.
Read-only limits
These MCP operations cannot create profiles, edit configuration, start or stop commands, or type into a shell. Reading output does not start a dormant terminal. The wrapper uses local app discovery and is not a hosted account connection or a remote execution service.
To create a terminal and submit one command from a local script, use the separate macOS command-line interface.
A missing discovery file, closed app, stale port, disabled access, or an incorrect custom configuration directory prevents reads. See MCP troubleshooting for recovery steps.