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

Clone the repository:

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

Install MCP dependency:

pip install mcp

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

track-it wrapper captures your process output
SQLite database stores process metadata
Log files preserve stdout/stderr streams
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.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables Claude to monitor and inspect running processes through a lightweight wrapper that captures stdout/stderr logs and stores process metadata in SQLite. Users can track any command execution and query process status, logs, and history through natural language.

Track-It Process Monitor