# 🚀 Terminal Capture MCP - Complete Setup Guide for New Computer

This guide will help you set up the complete Terminal Capture MCP system on a new computer from scratch. This enables GitHub Copilot and Claude Desktop to access your terminal output for better error analysis and debugging assistance.

## 📋 Prerequisites

- **Docker** installed on the target computer
- **VS Code** (if using with GitHub Copilot)
- **Claude Desktop** (if using with Claude)
- **Terminal access** (macOS Terminal, Windows PowerShell/WSL, Linux Terminal)

## 🎯 What This Setup Provides

- **Global terminal capture**: Works from ANY directory on the computer
- **Auto-capture**: 20+ common commands (npm, yarn, node, python, git, docker, etc.) automatically captured
- **Real-time access**: AI assistants can instantly access your most recent terminal output
- **Docker-based MCP server**: Isolated, containerized server that reads captured terminal output
- **Universal compatibility**: Works with GitHub Copilot, Claude Desktop, and other MCP-compatible tools

---

## 🚀 Quick Setup (Recommended)

**The easiest way to get started is using our automated setup script:**

> **📌 Note:** The automated script currently supports macOS and Linux. Windows users should use the [Manual Setup](#-manual-setup-alternative) section below.

### Option A: One-Line Setup (macOS/Linux)

# Download and run the automated setup script
curl -fsSL https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh | bash

### Option B: Download and Review First

# Download the script to review before running
curl -fsSL https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh -o setup.sh

# Review the script (optional but recommended)
cat setup.sh

# Make executable and run
chmod +x setup.sh
./setup.sh

**What this script does:**
- ✅ Checks Docker installation
- ✅ Pulls the MCP server Docker image
- ✅ Creates terminal capture directory and script
- ✅ Configures shell integration (Zsh/Bash)
- ✅ Provides AI tool configuration instructions
- ✅ Tests the setup automatically

**Script features:**
- 🔍 Detects your shell automatically (Zsh/Bash)
- 🛡️ Safe: Won't overwrite existing configurations
- 📝 Creates proper shell functions for 20+ commands
- ⚡ Ready to use immediately after running

**After running the script, skip to [Step 6: Test Terminal Capture](#-step-6-test-terminal-capture)**

---

## 🔧 Manual Setup (Alternative)

If you prefer manual setup or need to customize the installation:

### Step 1: Install Docker

#### macOS

# Install Docker Desktop from official website
open https://docs.docker.com/desktop/install/mac/

#### Windows

# Install Docker Desktop from official website
start https://docs.docker.com/desktop/install/windows-install/

#### Linux (Ubuntu/Debian)

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and log back in

**Verify Docker installation:**

docker --version
docker run hello-world

### Step 2: Pull the Docker MCP Server

# Pull the pre-built MCP server image
docker pull maniii97/terminal-capture-mcp-server:latest

### Step 3: Create Terminal Capture Script

# Create terminal capture directory
mkdir -p ~/.terminal-capture

# Download the capture script directly
curl -fsSL https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh -o temp-setup.sh

# Extract just the capture script part (lines 40-120)
sed -n '40,120p' temp-setup.sh | sed '1d;$d' > ~/.terminal-capture/terminal-capture-simple.sh

# Make executable
chmod +x ~/.terminal-capture/terminal-capture-simple.sh

# Clean up
rm temp-setup.sh

### Step 4: Configure Shell Integration

**For Zsh users (most macOS users):**

# Add to ~/.zshrc
cat >> ~/.zshrc << 'EOF'

# Terminal Capture MCP - Auto-load capture functions
if [ -f "$HOME/.terminal-capture/terminal-capture-simple.sh" ]; then
    source "$HOME/.terminal-capture/terminal-capture-simple.sh"
fi
EOF

**For Bash users:**

# Add to ~/.bashrc (Linux) or ~/.bash_profile (macOS)
if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS
    cat >> ~/.bash_profile << 'EOF'

# Terminal Capture MCP - Auto-load capture functions
if [ -f "$HOME/.terminal-capture/terminal-capture-simple.sh" ]; then
    source "$HOME/.terminal-capture/terminal-capture-simple.sh"
fi
EOF
else
    # Linux
    cat >> ~/.bashrc << 'EOF'

# Terminal Capture MCP - Auto-load capture functions
if [ -f "$HOME/.terminal-capture/terminal-capture-simple.sh" ]; then
    source "$HOME/.terminal-capture/terminal-capture-simple.sh"
fi
EOF
fi

**For Windows PowerShell:**

# Create PowerShell profile directory
New-Item -ItemType Directory -Force -Path (Split-Path $PROFILE)

# Create terminal capture directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.terminal-capture"

# Add terminal capture functions to PowerShell profile
@'
# Terminal Capture MCP for PowerShell
$TERMINAL_LOG_FILE = "$env:USERPROFILE\.terminal-capture\recent-output.log"

function Capture-Command {
    param([string]$Command)
    
    $timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ssK"
    $currentDir = Get-Location
    
    # Create log entry
    @"
=== $timestamp ===
Command: $Command
Directory: $currentDir
--- Output ---
"@ | Out-File -FilePath $TERMINAL_LOG_FILE -Encoding UTF8
    
    # Execute and capture
    Invoke-Expression $Command 2>&1 | Tee-Object -FilePath $TERMINAL_LOG_FILE -Append
    
    "--- Exit Code: $LASTEXITCODE ---`n" | Out-File -FilePath $TERMINAL_LOG_FILE -Append -Encoding UTF8
}

# Override common commands
function npm { Capture-Command "npm.cmd $args" }
function node { Capture-Command "node.exe $args" }
function python { Capture-Command "python.exe $args" }
function git { Capture-Command "git.exe $args" }
function docker { Capture-Command "docker.exe $args" }
function mvn { Capture-Command "mvn.cmd $args" }
function gradle { Capture-Command "gradle.bat $args" }

Write-Host "Terminal Capture MCP loaded for PowerShell" -ForegroundColor Green
'@ | Out-File -FilePath $PROFILE -Encoding UTF8

Write-Host "PowerShell profile created. Restart PowerShell to activate." -ForegroundColor Yellow

### Step 5: Reload Shell Configuration

**For macOS/Linux:**

# Reload your shell configuration
source ~/.zshrc    # For Zsh users
# OR
source ~/.bashrc   # For Bash users (Linux)
source ~/.bash_profile  # For Bash users (macOS)

**For Windows:**

# Reload PowerShell profile (or restart PowerShell)
. $PROFILE

**Verify terminal capture is loaded:**

*macOS/Linux:*

# Should show the capture function
which npm
# OR
type npm

*Windows:*

# Should show the PowerShell function
Get-Command npm

---

## 🧪 Step 6: Test Terminal Capture

> **Note:** If you used the automated setup script, terminal capture should already be working. This step verifies everything is functioning correctly.

**Test basic capture:**

# Test auto-capture
npm --version

# Check if it was captured
cat ~/.terminal-capture/recent-output.log

# Test manual capture
capture echo "Hello from terminal capture!"

# Check log again
cat ~/.terminal-capture/recent-output.log

**Test multiple commands:**

# Test different auto-captured commands
node --version
python3 --version
git --version

# Each command should appear in the log
tail -20 ~/.terminal-capture/recent-output.log

**Expected output in log file:**

=== 2025-08-04T22:45:47+05:30 ===
Command: command npm --version
Directory: /current/directory
--- Output ---
10.8.2
--- Exit Code: 0 ---

**For Windows users:**

# Test PowerShell capture
npm --version

# Check the log
Get-Content "$env:USERPROFILE\.terminal-capture\recent-output.log"

---

## 🤖 Step 7: Configure AI Tools

### Option A: Claude Desktop

**File location:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

**Configuration:**

{
  "mcpServers": {
    "terminal-capture": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "~/.terminal-capture:/terminal-capture",
        "maniii97/terminal-capture-mcp-server:latest"
      ],
      "env": {
        "TERMINAL_LOG_PATH": "/terminal-capture/recent-output.log"
      }
    }
  }
}

**⚠️ Important for Claude Desktop:** Replace `~/.terminal-capture` with the **absolute path**:
- **macOS/Linux:** `/Users/USERNAME/.terminal-capture:/terminal-capture`
- **Windows:** `C:\Users\USERNAME\.terminal-capture:/terminal-capture`

### Option B: GitHub Copilot (VS Code)

**File location:** VS Code Settings (File → Preferences → Settings → Open Settings JSON)

**Add this configuration:**

{
  "terminal.integrated.profiles.osx": {
    "zsh-with-capture": {
      "path": "zsh",
      "args": ["-c", "source ~/.zshrc && exec zsh"]
    }
  },
  "terminal.integrated.defaultProfile.osx": "zsh-with-capture",
  "github.copilot.chat.mcp.servers": {
    "terminal-capture": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "~/.terminal-capture:/terminal-capture",
        "maniii97/terminal-capture-mcp-server:latest"
      ]
    }
  }
}

**For Windows users, also add:**

{
  "terminal.integrated.profiles.windows": {
    "PowerShell-with-capture": {
      "path": "powershell.exe",
      "args": ["-Command", ". $PROFILE; powershell.exe"]
    }
  },
  "terminal.integrated.defaultProfile.windows": "PowerShell-with-capture"
}

---

## 🎯 Step 8: Restart and Test

1. **Restart your AI tool:**
- Close and reopen Claude Desktop
- Restart VS Code

2. **Test the complete system:**

   # Run a command that might have errors
   npm install nonexistent-package-12345
   
   # Ask your AI assistant:
   # "What was the error in my last command?"
   # "Check my recent terminal output for issues"
   # "Help me debug this npm error"

**Windows users:**

   # Test with an error command
   npm install nonexistent-package-12345
   
   # Ask your AI assistant the same questions

3. **Verify Docker MCP manually:**

*macOS/Linux:*

   # Test the Docker MCP server directly
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_recent_terminal_output","arguments":{}}}' | \
     docker run --rm -i -v ~/.terminal-capture:/terminal-capture \
     maniii97/terminal-capture-mcp-server:latest

*Windows:*

   # Test the Docker MCP server directly
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_recent_terminal_output","arguments":{}}}' | docker run --rm -i -v "$env:USERPROFILE\.terminal-capture:/terminal-capture" maniii97/terminal-capture-mcp-server:latest

---

## 🎉 You're All Set!

Your terminal capture MCP system is now fully configured! Here's what you can do:

### ✅ Features Available
- **Global capture**: Works from any directory
- **Auto-capture**: 20+ commands automatically captured
- **Real-time**: Instantly available to AI assistants
- **Clean logs**: Each command overwrites the previous
- **Docker isolated**: Containerized MCP server

### 💡 Usage Examples
Ask your AI assistant:
- "What was the error in my last command?"
- "Check my recent terminal output for issues"
- "Why did my npm install fail?"
- "Help me debug this Docker build error"
- "Analyze my recent git output"

### 📁 Important File Locations
- **Automated Setup Script:** [GitHub Gist](https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da)
- **Terminal capture script:** `~/.terminal-capture/terminal-capture-simple.sh`
- **Log file:** `~/.terminal-capture/recent-output.log`
- **Docker image:** `maniii97/terminal-capture-mcp-server:latest`

---

## 🐛 Troubleshooting

### Quick Setup Script Issues

**Script download fails:**

# Alternative download methods
wget https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh
# OR
curl -L https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh -o setup.sh

**Permission denied:**

# Make sure the script is executable
chmod +x setup.sh
./setup.sh

**Script says Docker not found:**

# Verify Docker installation
docker --version
which docker

# On macOS, make sure Docker Desktop is running
open -a Docker

### Terminal capture not working

# Check if functions are loaded
which npm
type npm

# Reload shell configuration
source ~/.zshrc  # or appropriate shell config

# Check log file exists
ls -la ~/.terminal-capture/

# Manual test
capture echo "test capture"
cat ~/.terminal-capture/recent-output.log

**For Windows:**

# Check if functions are loaded
Get-Command npm

# Reload PowerShell profile
. $PROFILE

# Check log directory
Get-ChildItem "$env:USERPROFILE\.terminal-capture"

### Docker MCP server issues

# Test Docker image
docker run --rm maniii97/terminal-capture-mcp-server:latest test

# Check volume mount
docker run --rm -v ~/.terminal-capture:/terminal-capture alpine ls -la /terminal-capture

# Check log file permissions
ls -la ~/.terminal-capture/recent-output.log

### AI tool connection issues
- Ensure absolute paths in configuration (especially for Claude Desktop)
- Restart AI tool after configuration changes
- Check Docker is running: `docker ps`

---

## ❓ Frequently Asked Questions

### Q: Is my terminal data secure?
**A:** Yes! Everything runs locally on your computer. The terminal capture only stores your most recent command output in a local file (`~/.terminal-capture/recent-output.log`). No data is sent to external servers.

### Q: Can I use this with multiple AI tools?
**A:** Absolutely! You can configure both Claude Desktop and VS Code GitHub Copilot to use the same terminal capture system simultaneously.

### Q: What if I don't want to capture certain commands?
**A:** You can run commands normally without the auto-capture by prefixing with `command`:

command npm install  # This won't be captured
npm install          # This will be captured

### Q: How do I uninstall terminal capture?
**A:** Remove the configuration from your shell config file:

# Remove these lines from ~/.zshrc or ~/.bashrc
# Terminal Capture MCP - Auto-load capture functions
if [ -f "$HOME/.terminal-capture/terminal-capture-simple.sh" ]; then
    source "$HOME/.terminal-capture/terminal-capture-simple.sh"
fi

Then restart your terminal or run `source ~/.zshrc`.

### Q: Can I add more commands to auto-capture?
**A:** Yes! Edit `~/.terminal-capture/terminal-capture-simple.sh` and add:

my-tool() { capture "command my-tool $*"; }

### Q: Why use Docker for the MCP server?
**A:** Docker ensures the MCP server works consistently across different systems and isolates it from your main environment. It also makes installation much simpler.

### Q: Does this slow down my terminal?
**A:** The impact is minimal. Commands are captured asynchronously, and only the output is logged, not the execution itself.

---

## 🚀 Advanced Usage

### Custom Commands
Add your own command overrides to the capture script:

# Add to ~/.terminal-capture/terminal-capture-simple.sh
my-custom-tool() { capture "command my-custom-tool $*"; }

### Multiple AI Tools
You can use the same terminal capture with multiple AI tools simultaneously. Just configure each tool with the same Docker MCP server.

### Development Workflows
The system works great for:
- Debugging build failures
- Analyzing test failures
- Understanding deployment issues
- Getting help with error messages
- Code review assistance

### Updating the System
To get the latest version:

# Update the Docker image
docker pull maniii97/terminal-capture-mcp-server:latest

# Re-run the setup script to get latest capture functions
curl -fsSL https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh | bash

### Performance Optimization
For better performance with large outputs:

# Limit log file size (optional)
echo "alias capture='capture_with_limit'" >> ~/.zshrc

capture_with_limit() {
    # Your custom capture function with size limits
    local cmd="$*"
    # ... implementation with head/tail to limit output
}

---

## 📚 Quick Reference

### Essential Commands

# Quick setup (macOS/Linux)
curl -fsSL https://gist.github.com/Maniii97/d9afaed3ee0d15e80949dbe1d18af3da/raw/capture-terminal-mcp-setup.sh | bash

# Check if capture is working
npm --version && cat ~/.terminal-capture/recent-output.log

# Manual capture any command
capture your-command-here

# Test Docker MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_recent_terminal_output","arguments":{}}}' | docker run --rm -i -v ~/.terminal-capture:/terminal-capture maniii97/terminal-capture-mcp-server:latest

# Update system
docker pull maniii97/terminal-capture-mcp-server:latest

### Key File Paths
| Platform | Capture Script | Log File | Shell Config |
|----------|---------------|----------|--------------|
| **macOS/Linux** | `~/.terminal-capture/terminal-capture-simple.sh` | `~/.terminal-capture/recent-output.log` | `~/.zshrc` or `~/.bashrc` |
| **Windows** | PowerShell Profile | `%USERPROFILE%\.terminal-capture\recent-output.log` | `$PROFILE` |

### Auto-Captured Commands
`npm`, `yarn`, `pnpm`, `node`, `bun`, `python`, `python3`, `pip`, `pip3`, `pipenv`, `poetry`, `make`, `cmake`, `cargo`, `go`, `mvn`, `gradle`, `javac`, `java`, `gcc`, `g++`, `clang`, `docker`, `docker-compose`, `git`

---

**🎯 Your terminal commands are now captured and available to AI assistants for intelligent debugging assistance!**

> 💡 **Need help?** Ask your AI assistant: *"What was my last terminal command?"* or *"Help me debug this error"*