MCP 服务器

Claude Code MCP Controller

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.

README

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)