How do I use terminal-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.

terminal-mcp

by JoasASantos

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

terminal-mcp

MCP server that executes shell commands and captures terminal output as styled PNG screenshots — perfect for pentest reports, documentation, and any workflow where you need professional-looking terminal captures.

Works with any MCP-compatible client: Claude Code, OpenAI Codex, Antigravity, Cursor, Windsurf, Cline, Continue, and more.

Features

Execute & capture: Run commands with full ANSI color preservation
Terminal-styled screenshots: Renders output as PNG with macOS window chrome, proper colors, and metadata
20 built-in themes: Tokyo Night, Dracula, Nord, Gruvbox, GitHub Dark, Kali, Ubuntu, and more
Report-ready: Watermarks, timestamps, exit codes, custom titles
Full ANSI support: 16 colors, 256-color palette, and 24-bit truecolor
Cross-platform: macOS and Linux support
Session capture management: List, re-render, and manage captures

Related MCP server: mcp2term

Screenshot Examples

Tokyo Night theme

Installation

Quick Setup (Recommended)

git clone https://github.com/JoasASantos/terminal-mcp.git
cd terminal-mcp
chmod +x setup.sh
./setup.sh

The setup script handles everything: dependency installation, build, and MCP client registration.

Manual Setup

git clone https://github.com/JoasASantos/terminal-mcp.git
cd terminal-mcp
npm install
npm run build

Linux Prerequisites

On Linux, Puppeteer requires some system libraries for Chromium:

Debian/Ubuntu:

sudo apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2

Fedora/RHEL:

sudo dnf install -y \
  nss atk at-spi2-atk cups-libs libdrm libxkbcommon \
  libXcomposite libXdamage libXrandr mesa-libgbm pango cairo alsa-lib

Arch Linux:

sudo pacman -S nss atk at-spi2-atk cups libdrm libxkbcommon \
  libxcomposite libxdamage libxrandr mesa pango cairo alsa-lib

Client Configuration

Claude Code

Automatic (via setup.sh):

./setup.sh
# Restart Claude Code after setup

Manual (via CLI):

claude mcp add terminal-mcp --scope user -e TERMINAL_MCP_DIR="$HOME/terminal-screenshots" -- node /path/to/terminal-mcp/dist/index.js

OpenAI Codex

Add to your Codex MCP configuration:

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp/dist/index.js"],
      "env": {
        "TERMINAL_MCP_DIR": "/path/to/screenshots"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp/dist/index.js"],
      "env": {
        "TERMINAL_MCP_DIR": "/path/to/screenshots"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP settings (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp/dist/index.js"],
      "env": {
        "TERMINAL_MCP_DIR": "/path/to/screenshots"
      }
    }
  }
}

Cline (VS Code)

Add to Cline's MCP server settings in VS Code:

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp/dist/index.js"],
      "env": {
        "TERMINAL_MCP_DIR": "/path/to/screenshots"
      }
    }
  }
}

Continue

Add to ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "terminal-mcp": {
        "command": "node",
        "args": ["/path/to/terminal-mcp/dist/index.js"],
        "env": {
          "TERMINAL_MCP_DIR": "/path/to/screenshots"
        }
      }
    }
  }
}

Antigravity

Add to your Antigravity MCP configuration:

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp/dist/index.js"],
      "env": {
        "TERMINAL_MCP_DIR": "/path/to/screenshots"
      }
    }
  }
}

Generic MCP Client

Any client supporting the Model Context Protocol can use terminal-mcp. The server communicates over stdio using JSON-RPC. Configure it with:

Command: node
Args: ["/path/to/terminal-mcp/dist/index.js"]
Env (optional): TERMINAL_MCP_DIR — directory for saved screenshots

Tools

Tool	Description
`terminal_exec_screenshot`	Primary tool. One command = one PNG. Execute any shell command and get a screenshot
`terminal_exec`	Execute a command and capture output for later screenshot
`terminal_screenshot`	Render a previously captured output as PNG
`terminal_screenshot_text`	Render arbitrary text as a terminal PNG
`terminal_list_captures`	List all captures in the current session
`terminal_list_screenshots`	List saved PNG files
`terminal_themes`	List available themes

Works with any command: nmap, curl, gobuster, nikto, sqlmap, ls, docker, kubectl, git, python, gcc — anything that runs in a shell.

Themes (20)

Theme	Description
tokyonight	Dark blue, clean and modern (default)
dracula	Classic purple-accented dark
monokai	Warm dark with vibrant colors
catppuccin	Soft pastel dark (Mocha)
nord	Arctic blue-gray palette
gruvbox	Retro warm dark with earthy tones
solarized	Solarized Dark, precision colors
onedark	Atom One Dark
material	Material Design dark
ayu	Ayu Dark, minimal contrast
github	GitHub Dark
cobalt	Deep blue with bright accents
hacker	Green-on-black matrix style
macos	Native macOS Terminal.app dark
kali	Kali Linux terminal
parrot	Parrot OS terminal
ubuntu	Ubuntu terminal (aubergine)
powershell	Windows PowerShell blue
retro	Retro amber phosphor CRT
light	Light theme for print-friendly reports

Screenshot Options

Option	Type	Default	Description
`theme`	string	`tokyonight`	Color theme (see list above)
`show_chrome`	boolean	`true`	macOS window chrome with traffic lights
`font_size`	number	`14`	Font size in pixels
`title`	string	command name	Window title bar text
`prompt`	string	`$`	Shell prompt prefix
`show_timestamp`	boolean	`true`	Show timestamp in footer
`watermark`	string	—	Watermark text (bottom-right)
`save_path`	string	auto	Full path for the output PNG
`width`	number	auto	Fixed terminal width in pixels
`max_width`	number	`980`	Maximum terminal width
`max_lines`	number	all	Truncate output after N lines
`line_height`	number	`1.4`	Line spacing multiplier
`scale`	number	`2`	Resolution: 1 = 1x, 2 = retina, 3 = 3x
`compact`	boolean	`false`	Reduced padding for smaller screenshots

Usage Examples

Basic command screenshot

terminal_exec_screenshot({ command: "nmap -sV target.com", theme: "hacker" })

Pentest report with watermark

terminal_exec_screenshot({
  command: "nikto -h https://target.com",
  theme: "tokyonight",
  watermark: "CONFIDENTIAL - Pentest Report 2024",
  title: "Nikto Web Scanner"
})

Screenshot arbitrary text

terminal_screenshot_text({
  text: "Finding: SQL Injection in /api/users\nSeverity: Critical\nCVSS: 9.8",
  title: "Vulnerability Report",
  theme: "dracula"
})

Environment Variables

Variable	Default	Description
`TERMINAL_MCP_DIR`	`~/terminal-screenshots`	Directory for saved screenshots

Requirements

Node.js 18+
Puppeteer (bundled — downloads Chromium on first run)
On Linux: system libraries for headless Chromium (see Linux Prerequisites)

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

screenshotA
com.apiscreenshot
Screenshot any URL/HTML as PNG/JPEG/WebP, or read it as clean Markdown/text for LLMs.
Browser Automation Image & Video Processing
2
https://apiscreenshot.com/mcp
shotkitA
net.shotkit
Screenshot any URL, HTML or Markdown in a real browser, and read web pages as Markdown.
Browser Automation Web Scraping
21
https://shotkit.net/mcp
HTML/CSS to Image APIA
io.github.htmlcsstoimage
Generate images and PDFs from HTML/CSS, live websites, and reusable templates.
Image & Video Processing
3517
https://mcp.hcti.io
OpenScreenShot
io.github.PGHQdev
Capture website screenshots (viewport or full page) with local Chrome, or on OpenScreenShot Cloud.
Browser Automation Web Scraping Image & Video Processing
190
https://cloud.openscreenshot.app/mcp

Related MCP Servers

Terminal Control MCP
taskhub-sh
A
license
A
quality
D
maintenance
Enables AI agents to interact with terminal-based TUI applications by capturing visual terminal output as PNG screenshots and simulating keyboard input through a virtual X11 display.
Updated a year ago (2025-07-25 20:36 UTC)
4
2
Apache 2.0
mcp2term
Shell Access Command Line OS Automation
FreddyE1982
F
license
B
quality
D
maintenance
Enables safe execution of system shell commands with real-time streaming output and rich metadata capture. Provides configurable command execution with timeout controls, environment management, and extensible plugin architecture for monitoring command lifecycles.
Updated a year ago (2025-10-15 15:14 UTC)
4
-
cli-mcp
Shell Access Command Line
gabry848
F
license
Not graded
quality
D
maintenance
Provides secure execution of terminal commands (PowerShell, CMD, shell) with configurable security policies including command blocking, path restrictions, and timeout.
Updated a year ago (2025-11-28 18:44 UTC)
1
-
spectatty
Command Line Shell Access Developer Tools
dayvidwang
A
license
Not graded
quality
D
maintenance
Enables AI agents to spawn and interact with real terminal sessions, capturing screenshots of rendered TUI output and sharing live sessions for debugging.
Updated 7 months ago (2026-04-10 22:33 UTC)
5 npm
1
MIT

terminal-mcp

Features

Screenshot Examples

Installation

Quick Setup (Recommended)

Manual Setup

Linux Prerequisites

Client Configuration

Claude Code

OpenAI Codex

Cursor

Windsurf

Cline (VS Code)

Continue

Antigravity

Generic MCP Client

Tools

Themes (20)

Screenshot Options

Usage Examples

Basic command screenshot

Pentest report with watermark

Screenshot arbitrary text

Environment Variables

Requirements

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Terminal Control MCP

mcp2term

cli-mcp

spectatty