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
π‘ 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.
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
π 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)
βοΈ Configuration (Optional)
The system uses sensible defaults, but you can customize settings:
Key settings:
SUPERVISOR_PORT=8080
- Supervisor HTTP server portMCP_PORT=8000
- MCP server port for ChatGPTNGROK_PORT=8000
- Port for ngrok tunnelLOG_LEVEL=INFO
- Logging level (DEBUG, INFO, WARNING, ERROR)
π§ Essential Make Commands
π 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:
Usage:
Via ChatGPT (Once Connected)
ChatGPT Commands:
Via Direct HTTP API
1. Test Locally with ChatGPT (Recommended)
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 |
| Show all active sessions | "What sessions are running?" |
| Start new Claude-Code | "Create a session in my project folder" |
| Send commands to session | "Tell the web-app session to add tests" |
| Retrieve session output | "Show me recent logs from api session" |
| Check session details | "What's the status of session X?" |
| Stop a session | "Terminate the stuck session" |
| Find pending prompts | "Any sessions waiting for input?" |
| Answer interactive prompts | "Tell it 'yes'" |
| Search sessions (ChatGPT requirement) | "Find sessions with 'web-app' in name" |
| 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:
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:
π§ Development Testing (Automated)
For code validation and CI/CD:
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
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:
Lunch Break:
End of Day:
π€ 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.
π Useful Links
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables remote control and monitoring of Claude Code sessions from mobile devices through ChatGPT Custom Connectors. Allows creating, managing, and interacting with multiple Claude Code sessions via natural language commands from anywhere.
- β οΈ Important: Personal DIY Project
- π― What This Solves
- β‘ Quick Demo
- π¬ Real-World Example
- ποΈ Architecture
- π Prerequisites
- π Quick Start
- π οΈ MCP Tools Available
- π Testing & Development
- π’ Deployment Approach
- π Security Architecture & Session Management
- π± Mobile Workflow Example
- π€ Contributing
- π License
- π Useful Links