track-it: MCP Process Wrapper

A lightweight process tracker that enables Claude to monitor and inspect running processes through the Model Context Protocol (MCP).

Features

• 🚀 Simple CLI wrapper - Just prepend track-it to any command

• 🔍 Environment variable support - Pass env vars to tracked processes

• 📝 Separate stdout/stderr logs - Independent capture of output streams

• 💾 Persistent SQLite storage - Survives restarts, queryable history

• 🔒 Read-only MCP interface - Claude can observe but not execute

• 📊 Real-time monitoring - Tail logs of running processes

• 🛡️ Signal handling - Clean shutdown with Ctrl+C

Quick Start

Installation

1. Clone the repository:

git clone https://github.com/scottmsilver/mcp-track-it.git
cd mcp-track-it

2. Install MCP dependency:

pip install mcp

3. Run the installer:

./install-and-test.sh

This will:

• Check Python installation

• Test the track-it wrapper

• Configure Claude's MCP settings

• Run a test process to verify everything works

Basic Usage

# Simple command
./track-it echo "Hello World"

# With custom ID
./track-it --id myapp python server.py

# With environment variables
./track-it PORT=8080 DEBUG=true -- python app.py

# Multiple env vars and options
./track-it --id webserver PORT=3000 HOST=0.0.0.0 -- npm start

Environment Variable Support

The new syntax supports passing environment variables to tracked processes:

# Format: track-it [options] [ENV=value ...] [--] command [args]

# Examples:
./track-it DATABASE_URL=postgres://localhost/mydb -- python manage.py runserver
./track-it --id worker REDIS_HOST=localhost WORKERS=4 -- python worker.py

Use -- to separate environment variables from the command when needed.

Claude Integration

Once installed, Claude can monitor your processes using these phrases:

• "List all my tracked processes"

• "Show me the logs for [process-id]"

• "Check if my server is still running"

• "Find any errors in the process logs"

What Claude Sees

When you run:

./track-it --id myserver PORT=8080 -- python server.py

Claude will see:

• Process ID: myserver

• Status: running or completed

• Full command with arguments

• Environment variables that were set

• Complete stdout/stderr logs

• Exit code when completed

File Structure

mcp-track-it/
├── track-it                    # Main CLI wrapper
├── mcp_server.py              # MCP server for Claude
├── process_registry.py        # SQLite database interface
├── install-and-test.sh        # Main installer
├── process_logs/              # Log files (auto-created)
│   ├── [process-id].log       # Combined stdout+stderr
│   ├── [process-id].stdout.log
│   └── [process-id].stderr.log
└── process_registry.db        # SQLite database (auto-created)

How It Works

1. track-it wrapper captures your process output

2. SQLite database stores process metadata

3. Log files preserve stdout/stderr streams

4. MCP server provides read-only access to Claude

User runs: track-it python app.py
    ↓
Creates 3 log files + DB entry
    ↓
Process runs with real-time output
    ↓
Claude can query via MCP server

Advanced Configuration

Custom Log Directory

Set the environment variable:

export MCP_PROCESS_WRAPPER_LOG_DIR=/path/to/logs
./track-it python app.py

Manual MCP Configuration

If you need to manually configure Claude's MCP settings, add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "process-wrapper": {
      "command": "python3",
      "args": ["/path/to/mcp-track-it/mcp_server.py"],
      "env": {
        "MCP_PROCESS_WRAPPER_LOG_DIR": "/path/to/logs",
        "MCP_PROCESS_REGISTRY_DB": "/path/to/process_registry.db"
      }
    }
  }
}

Troubleshooting

Permission denied when running track-it:

chmod +x track-it

Claude can't see processes:

• Restart Claude Code after installation

• Verify MCP server is listed: Ask Claude to run /mcp command

Process gets stuck when hitting Ctrl+C:

• Update to the latest version (this bug was fixed)

Logs not appearing:

• Check write permissions in the log directory

• Verify disk space is available

Recent Improvements

• ✅ Environment variable support - Pass env vars to tracked processes

• ✅ Absolute path storage - Reliable log file access across directories

• ✅ Fixed signal handling - Clean shutdown without infinite loops

• ✅ Better path resolution - MCP server correctly finds logs from any working directory

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - See LICENSE file for details.

Author

Created as a lightweight alternative to complex process managers, specifically designed for Claude MCP integration.