Claude-Code MCP Controller 🚀

A local MCP (Model Context Protocol) server for remotely controlling and monitoring Claude Code sessions via ChatGPT Custom Connectors. Perfect for mobile workflows, remote development, and managing multiple coding sessions from anywhere.

⚠️ Important: Personal DIY Project

This is a personal DIY project for managing my own Claude Code sessions via ChatGPT Custom Connectors on mobile.

The main focus is leveraging ChatGPT Custom Connectors, which are custom MCP servers that extend ChatGPT's capabilities.

✅ Works great for personal/temporary use with ephemeral ngrok URLs
❌ NOT designed for production or long-term deployment
❌ NO security hardening (minimal auth, designed for temporary use)
🎯 Use case: Temporary remote control via ChatGPT mobile while away from Mac
🤝 Community: More robust solutions will likely emerge from the community soon

Use at your own risk. If you need production-ready session management, please wait for community solutions or fork and harden this project.

🎯 What This Solves

Problem: You're away from your Mac but need to check on or control your Claude-Code sessions.

Solution: Use ChatGPT Custom Connectors as a remote control for your Claude Code sessions through MCP.

Real-World Use Cases

📱 Mobile Development: Check session status while commuting
🏠 Remote Work: Monitor long-running tasks from anywhere
🔄 Multi-Project Management: Control multiple Claude-Code sessions simultaneously
🚨 Stuck Command Recovery: Handle interactive prompts that block sessions
📊 Session Monitoring: Get logs and status updates in natural language

⚡ Quick Demo

You: "What Claude-Code sessions are running?" ChatGPT: "You have 2 active sessions: - web-app_a1b2: Building user dashboard (last active 5 min ago) - api_c3d4: Adding authentication (last active 2 min ago)" You: "Tell the web-app session to run the tests" ChatGPT: "✅ Message sent! The session is now running tests..." You: "Any sessions stuck waiting for input?" ChatGPT: "Yes! The api session is asking: 'Install new dependency? [y/n]'" You: "Tell it yes" ChatGPT: "✅ Response sent! Session will continue with installation."

💡 Test this demo locally! Start the server + supervisor, then ngrok http 8000 to try it yourself with real ChatGPT before deploying.

🎬 Real-World Example

Here's an actual conversation showing how to use ChatGPT to control Claude Code and build features on-the-go:

Scenario: Adding next/previous navigation to a blog's notes pages while away from your Mac.

You: "How many Claude Code sessions running?" ChatGPT: "There is 1 active Claude-Code session running now: - claude-mostafa-xyz (active, in claude-code-mcp-controller)" You: "For this project, I want to add navigation for notes - basically previous/next post functionality" ChatGPT: "I've sent your request to Claude. It's analyzing the notes structure now..." You: "Check logs" ChatGPT: "Claude analyzed the project and suggested: - Add a NoteNavigation component with Previous/Next links - Create getAdjacentPosts(slug) helper in lib/mdx - Update notes/[slug]/page.tsx to use the new component - Fully typed, accessible design Do you want it to implement this?" You: "Sounds good, go for it" ChatGPT: "Claude has started implementing..." You: "Check logs" ChatGPT: "Claude created NoteNavigation.tsx and is asking to update page.tsx to integrate it. Should I approve?" You: "Yes please" ChatGPT: "✅ Navigation wired in. Previous/Next links are now integrated with your existing theme." You: "Ask it to run checks and build to make sure everything working" ChatGPT: "Claude is running typecheck... ✅ Passed! Now running build... ✅ Build successful! Your notes now have working previous/next navigation!"

What happened:

💬 Natural conversation with ChatGPT from mobile
🔍 Claude Code analyzed the codebase structure
🏗️ Implemented 3 files: helper function, component, page integration
✅ Ran TypeScript checks and production build
🎨 Followed existing design system automatically

All done from your phone while commuting! 🚀

🏗️ Architecture

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ ChatGPT │◄──►│ Local MCP │◄──►│ Mac Supervisor │ │ Mobile App │ │ + ngrok tunnel │ │ (Local Agent) │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ │ HTTPS via ngrok │ No Authentication ▼ (until OpenAI fixes OAuth) ┌─────────────────┐ │ Existing Claude │ │ Sessions (PTYs) │ │ • session_1 │ │ • session_2 │ │ • session_N │ └─────────────────┘

📋 Prerequisites

Before you begin, ensure you have:

Python 3.10+ installed
tmux installed (brew install tmux on macOS)
ngrok installed and configured (brew install ngrok on macOS)
Claude Code installed and working
macOS (tested on macOS, may work on Linux with modifications)

🚀 Quick Start

⚡ One-Command Setup (Recommended)

# Clone and setup everything git clone <your-repo> cd claude-code-mcp-controller make setup # Add session creation alias to your shell echo "alias cs='claude_session() { tmux new-session -d -s \"claude-\${1:-session}\" -c \"\${2:-\$(pwd)}\" \"claude\" && echo \"✅ Started claude-\$1\"; }; claude_session'" >> ~/.zshrc source ~/.zshrc # Create your first Claude session cs myproject

⚙️ Configuration (Optional)

The system uses sensible defaults, but you can customize settings:

# Copy example config cp env.example .env # Edit as needed (optional) nano .env

Key settings:

SUPERVISOR_PORT=8080 - Supervisor HTTP server port
MCP_PORT=8000 - MCP server port for ChatGPT
NGROK_PORT=8000 - Port for ngrok tunnel
LOG_LEVEL=INFO - Logging level (DEBUG, INFO, WARNING, ERROR)

🔧 Essential Make Commands

# Show available commands make help # Complete project setup make setup # Start services make run-supervisor # Start supervisor make run-server # Start MCP server make ngrok # Start ngrok tunnel for ChatGPT (requires ngrok installed) # Development make test # Test the system make format # Format code make lint # Lint code # Cleanup make clean # Clean up files

🚀 Creating & Managing Claude Sessions

The supervisor discovers and manages tmux sessions with names starting with claude-. You can create sessions manually or via ChatGPT.

Quick Setup: Shell Alias (Recommended)

Add this alias to your shell for easy session creation:

# Add to ~/.zshrc or ~/.bashrc alias cs='claude_session() { local name="${1:-session}" local dir="${2:-$(pwd)}" tmux new-session -d -s "claude-$name" -c "$dir" "claude" && echo "✅ Started claude-$name in $dir" tmux list-sessions | grep "claude-$name" }; claude_session' # Reload your shell config source ~/.zshrc # or ~/.bashrc

Usage:

# Create a session in current directory cs myproject # Create a session in specific directory cs webapp ~/projects/webapp # List all Claude sessions tmux list-sessions | grep claude- # Attach to a session to see what's happening tmux attach -t claude-myproject # (Detach with Ctrl+B, then D) # Kill a session when done tmux kill-session -t claude-myproject

Via ChatGPT (Once Connected)

# 1. Start supervisor (in one terminal) make run-supervisor # 2. Start MCP server (in another terminal) make run-server # 3. Connect ChatGPT to your MCP server # 4. Use ChatGPT commands:

ChatGPT Commands:

"Create a new Claude-Code session called 'my-project'" "List my active sessions" "Send message to session 'my-project': 'ls -la'" "Show me logs from session 'my-project'" "Terminate session 'my-project'"

Via Direct HTTP API

# Create session curl -X POST http://localhost:8080/sessions \ -H "Content-Type: application/json" \ -d '{"name": "test-session", "working_dir": "/path/to/project"}' # List sessions curl http://localhost:8080/sessions # Send message curl -X POST http://localhost:8080/sessions/SESSION_ID/message \ -H "Content-Type: application/json" \ -d '{"message": "Hello Claude-Code!"}' # Get logs curl http://localhost:8080/sessions/SESSION_ID/logs # Terminate session curl -X DELETE http://localhost:8080/sessions/SESSION_ID

1. Test Locally with ChatGPT (Recommended)

# Clone and setup git clone <your-repo> cd claude-code-mcp-controller make setup # Start supervisor (Terminal 1) make run-supervisor # Start MCP server (Terminal 2) make run-server # Start ngrok tunnel (Terminal 3) make ngrok # Test the system (Terminal 4) make test

Configure ChatGPT:

Add MCP connector: https://your-ngrok-url.ngrok.app (root path, no /mcp suffix)
Test: "What Claude-Code tools are available?"

2. Local Development Setup (Current Approach)

Why Local over Cloud:

Need access to your Mac's existing Claude sessions
Supervisor must run locally to manage local processes
Cloud deployment can't control local Mac sessions

Current Status:

✅ Local MCP server working with FastMCP 2.12.4
✅ ngrok tunnel for ChatGPT connectivity
⏳ OAuth pending (ChatGPT OAuth currently has known issues)
⏳ Supervisor component for Claude session management

🛠️ MCP Tools Available

Tool	Purpose	ChatGPT Example
`list_sessions`	Show all active sessions	"What sessions are running?"
`create_session`	Start new Claude-Code	"Create a session in my project folder"
`send_message`	Send commands to session	"Tell the web-app session to add tests"
`get_logs`	Retrieve session output	"Show me recent logs from api session"
`get_session_status`	Check session details	"What's the status of session X?"
`terminate_session`	Stop a session	"Terminate the stuck session"
`check_prompts`	Find pending prompts	"Any sessions waiting for input?"
`respond_to_prompt`	Answer interactive prompts	"Tell it 'yes'"
`search`	Search sessions (ChatGPT requirement)	"Find sessions with 'web-app' in name"
`fetch`	Get session data (ChatGPT requirement)	"Get full details for session X"

📋 Testing & Development

🎯 Local ChatGPT Testing (Recommended)

Test the real end-to-end experience with ChatGPT locally before deploying:

# Terminal 1: Start supervisor make run-supervisor # Terminal 2: Start MCP server make run-server # Terminal 3: Start ngrok tunnel make ngrok # Terminal 4: Test the system make test

Then connect ChatGPT:

Configure ChatGPT: Add MCP connector with https://your-ngrok-url.ngrok.app (root path)
Test mobile workflow: Use ChatGPT mobile app to control Claude-Code remotely

Test scenarios in ChatGPT:

"What Claude-Code tools are available?" "List my Claude-Code sessions" "Create a new session called mobile-test" "Tell the mobile-test session to list files" "Show me recent logs from that session"

🔧 Development Testing (Automated)

For code validation and CI/CD:

# Test the system make test # Format code make format # Lint code make lint

Local vs Production Testing

Testing Method	Purpose	When to Use
ChatGPT Local	Real UX validation	Before deployment, mobile testing
Automated Tests	Code validation	Development, CI/CD
FastMCP Cloud	Production testing	Final validation

Priority: Always test with ChatGPT locally first - it's your source of truth for user experience.

🚢 Deployment Approach

Current: Local with ngrok (Recommended)

✅ Direct Mac Access: Control local Claude sessions
✅ FastMCP 2.12.4: Production-ready MCP framework
✅ SSE Transport: JSON-RPC 2.0 over HTTPS via ngrok
✅ Ephemeral Security: ngrok URLs expire when tunnel closes
⏳ No Authentication: Temporary until OpenAI fixes OAuth

Security Status

Current Implementation:

I couldn't get OAuth working with ChatGPT at this stage
ChatGPT's OAuth workflow for MCP connectors has known issues (community confirmed)
Using ephemeral ngrok URLs as a practical workaround for personal use
URLs expire when tunnel closes, limiting exposure window

Important:

This is a DIY/personal project, not production software
Use only for temporary sessions, not long-term deployment
OAuth will be implemented once ChatGPT properly supports it

Why Not Cloud Deployment?

Cloud deployment (FastMCP Cloud, etc.) cannot solve the core use case:

Need local supervisor to access existing Claude sessions
Sessions run as local processes on your Mac
Remote server cannot control local Mac processes

🔒 Security Architecture & Session Management

Why the Supervisor Only Manages Sessions It Creates

Important: The supervisor only tracks sessions it creates - this is intentional security design, not a limitation.

🔒 Security Principles

Session Isolation: Each session is sandboxed with controlled lifecycle
Process Ownership: Only manages processes it spawns (prevents hijacking)
Secure IDs: Cryptographically secure UUIDs for all session identifiers
Audit Trail: Complete tracking of session creation → management → termination
Least Privilege: No automatic access to external processes

🎯 What This Means

✅ Safe: Can't accidentally control random processes on your system
✅ Predictable: All sessions follow same security model
✅ Auditable: Complete history of session management
❌ Convenient: Won't auto-detect existing Claude-Code sessions

🔄 Architecture Flow

ChatGPT → MCP Server → Supervisor → SessionManager → ClaudeWrapper → Claude-Code Process

Each layer adds security controls and isolation.

Security Features (MCP 2025-03-26 Compliant)

Current Implementation:

🔒 Secure Sessions: Cryptographically secure UUID session IDs
🌐 HTTPS Only: All endpoints encrypted via ngrok
🚪 Session Isolation: Each Claude-Code session sandboxed
📝 Audit Logging: Complete MCP request/response tracking
🚫 Command Validation: Restrict dangerous operations
⏳ Ephemeral URLs: ngrok tunnels expire when closed

Ready for OAuth (when ChatGPT fixes issues):

🔐 OAuth 2.1 with PKCE: RFC-compliant authorization flows
🏢 Dynamic Client Registration: RFC7591 support for new clients
🔍 Authorization Server Metadata: RFC8414 endpoint discovery
🛡️ DNS Rebinding Protection: Origin header validation
🔄 Token Rotation: Access token expiration and refresh

📱 Mobile Workflow Example

Morning Commute:

You: "Start a new session for my mobile app project" ChatGPT: "Created session mobile-app_x7y8 in ~/projects/mobile-app" You: "Tell it to run the test suite and fix any failures" ChatGPT: "Message sent! The session is running tests..."

Lunch Break:

You: "How's the mobile app session doing?" ChatGPT: "Session is active. Recent activity shows: - Fixed 3 test failures ✅ - Updated component tests ✅ - Waiting for your input on TypeScript migration" You: "Tell it to proceed with TypeScript migration" ChatGPT: "Message sent! Session will begin TypeScript migration."

End of Day:

You: "Show me what the mobile session accomplished today" ChatGPT: "Session mobile-app_x7y8 completed: - Fixed all test failures - Migrated 15 components to TypeScript - Added new authentication module - Session has been active for 8 hours" You: "Great! Terminate that session" ChatGPT: "✅ Session terminated. All work has been committed."

🤝 Contributing

This is an open-source project designed for the Claude Code community!

Fork the repo
Create feature branch: git checkout -b feature/amazing-feature
Setup and test: make setup && make test
Format and lint: make format && make lint
Commit with good messages: Follow Conventional Commits
Submit pull request

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ for the

Turn your iPhone into a remote control for your Mac's Claude Code sessions using ChatGPT Custom Connectors.

Claude Code MCP Controller