Claude-Code

You can run a local Claude-Code MCP Server to remotely control and monitor Claude-Code sessions from ChatGPT Custom Connectors. This server exposes a simple HTTP API you can reach from your MCP client to create, manage, and interact with Claude-Code sessions running on your Mac. It’s designed for quick, personal remote control and mobile workflows, with ephemeral tunnels for easy testing.

How to use

Connect your MCP client to the local Claude-Code MCP Server and start by listing your active Claude-Code sessions. Create a new session for a project, then send messages to that session to run commands or interact with Claude-Code. You can retrieve logs to see output and status, check session details, or terminate a session when you’re done. The flow is simple: list sessions → create or select a session → send messages → check logs or status → terminate when finished.

Typical usage patterns include monitoring multiple Claude-Code sessions from mobile, sending commands to run tests, and handling prompts that require interactive input. You can ask for recent logs to diagnose issues, check which sessions are active, and keep track of session status over time. When a session finishes or you terminate it, the MCP Server records the action for an auditable history.

How to install

Prerequisites you need before running the MCP server:

• Python 3.10+
• tmux
• ngrok
• Claude Code (installed and working)
• macOS (tested) or Linux compatibility adjustments may apply

Install and run steps you can follow to set up the server locally:

# 1) Clone the project
# (Replace with your actual repository location)
git clone <your-repo>
cd claude-code-mcp-controller

# 2) Install dependencies and set up environment
make setup

# 3) Start the supervisor (local process manager)
make run-supervisor

# 4) Start the MCP server (HTTP API for MCP clients)
make run-server

# 5) Start an ngrok tunnel to expose the MCP server to ChatGPT
make ngrok

# 6) Run tests to verify the setup
make test

# 7) In your MCP client, configure the MCP connector with the exposed URL
# Example base URL provided by ngrok in your terminal output

Configuration and security notes

The server is designed for local development and testing. It uses ephemeral ngrok URLs for exposing the MCP API to ChatGPT connections and does not implement production-grade authentication yet. You will typically run everything on your Mac, and the ngrok tunnel provides a temporary public endpoint that expires when the tunnel closes.

Key ports and settings you may see in the configuration include the supervisor port, MCP port, and the ngrok port used for tunneling. You can adjust logging level to control verbosity during development.

Usage details for HTTP API (quick reference)

From a client connected to the MCP Server, you can perform the following actions through HTTP endpoints:

• List all Claude-Code sessions
• Create a new Claude-Code session
• Send a message to a specific session
• Retrieve logs for a session
• Check the status of a session
• Terminate a session

Troubleshooting and tips

If you are testing on mobile, ensure the ngrok tunnel is active and the base URL you configure in your MCP client points to the ngrok URL. Check that the MCP server is running and reachable from your device. For debugging, increase the log level to DEBUG to surface more details about requests and responses.

For local testing, keep sessions isolated and terminate ones you no longer need to avoid resource contention. If a session seems unresponsive, inspect its logs and consider terminating and restarting the session.

Available tools

list_sessions

Show all active Claude-Code sessions

create_session

Start a new Claude-Code session in a working directory

send_message

Send a command or message to a specific Claude-Code session

get_logs

Retrieve output logs for a session

get_session_status

Check details and status of a session

terminate_session

Stop a Claude-Code session gracefully