chatgpt-mcp

Linux 컴퓨터에서 명시적으로 구성된 기능을 ChatGPT 또는 호환되는 MCP 클라이언트에 노출하는 무상태(stateless) MCP 서버입니다.

ChatGPT / MCP client
        |
        | MCP 2026-07-28
        v
chatgpt-mcp
        |
        | typed ComputerAdapter seam
        v
local operating system

ChatGPT가 호출할 도구를 선택합니다. chatgpt-mcp는 로컬 기능 구성에 대해 호출을 검증하고 작업을 수행합니다. 이는 두 번째 플래너가 아닌 얇은 프로토콜 어댑터이며, 자체적인 대화형 승인 루프를 추가하지 않습니다.

아키텍처: SPEC.md. 제공 이력: PLAN.md. 상세 ChatGPT/터널 가이드: docs/CHATGPT.md.

기능(Capabilities)

system.info를 제외한 모든 계열은 옵트인(opt-in) 방식입니다. 비활성화된 기능 계열은 실용적인 범위 내에서 MCP 도구 검색에서 제외됩니다.

요구 사항

핵심 서버:

• Linux

• Node.js 22+

• pnpm 11.20.0 (설치 프로그램이 Corepack 또는 npx를 통해 고정된 버전을 획득)

• ./install.sh가 설치하는 영구 터널용 systemd 사용자 서비스

활성화하는 항목에 따라 선택적 호스트 명령이 필요합니다:

• 서비스: systemctl

• 브라우저 열기: xdg-open

• 데스크톱 입력: xdotool

• 스크린샷: grim, gnome-screenshot, scrot 또는 ImageMagick import 중 하나

빠른 설치 프로그램은 누락된 경우 현재 공식 OpenAI tunnel-client와 일반적인 Debian/Ubuntu 데스크톱 헬퍼를 설치할 수 있습니다.

빠른 설치: ChatGPT + Linux 컴퓨터

단일 컴퓨터의 경우 권장 경로는 다음과 같습니다:

ChatGPT Developer Mode
        |
OpenAI Secure MCP Tunnel
        |
        | outbound HTTPS
        v
tunnel-client on your computer
        |
        | stdio
        v
chatgpt-mcp

공개 인바운드 리스너가 필요하지 않습니다.

빠른 설치 프로그램은 의도적으로 config.full.example.json을 사용하며, 이는 소유자가 제어하는 광범위한 권한을 부여합니다: /부터의 파일시스템 읽기/쓰기, 와일드카드 실행 파일 접근, 프로세스/서비스 제어, 브라우저 열기, 스크린샷, 지원되는 데스크톱 입력. 더 좁은 권한이 필요하면 config.example.json과 수동 설정을 대신 사용하세요.

1. OpenAI MCP 터널 생성

다음을 엽니다:

https://platform.openai.com/settings/organization/tunnels

터널을 생성하고 ID를 복사합니다. 다음과 같은 형식입니다:

tunnel_0123456789abcdef0123456789abcdef

ChatGPT 사용을 위해, 터널을 해당 터널을 볼 수 있어야 하는 ChatGPT 워크스페이스/계정과 연결하세요.

현재 권한 구분:

• 터널 생성/편집/삭제: Tunnels Read + Manage

• tunnel-client 실행 또는 ChatGPT에서 터널 선택: Tunnels Read + Use

2. 런타임 API 키 생성

다음을 엽니다:

https://platform.openai.com/settings/organization/api-keys

일반 런타임 API 키를 생성합니다. 장기 실행 터널 데몬에는 Admin API 키를 사용하지 마십시오.

설치 프로그램은 숨겨진 터미널 입력으로 결과 sk-... 값을 요청하고, 제한된 권한으로 .secrets/runtime-api-key에 로컬로 저장합니다.

터널에 API 키가 필요한 이유는 무엇인가요?

키는 OpenAI의 터널 제어 평면(tunnel control plane) 에 tunnel-client를 인증합니다. 로컬 데몬이 선택한 터널을 사용할 권한이 있음을 증명합니다.

이 키는 chatgpt-mcp가 OpenAI 모델 API를 호출하는 데 사용되지 않습니다. 이 설정에서 ChatGPT는 이미 모델/클라이언트이며, Secure MCP Tunnel은 해당 ChatGPT 대화가 로컬 MCP 서버에 도달할 수 있게 하는 프라이빗 전송 수단일 뿐입니다.

tunnel_...   = which tunnel this computer belongs to
sk-...       = permission for tunnel-client to use that tunnel

chatgpt-mcp는 이 런타임 키로 /v1/responses 또는 기타 모델 추론 요청을 하지 않습니다. OpenAI API 모델 과금은 ChatGPT 구독 사용과 별개입니다. 현재 Secure MCP Tunnel 문서는 별도의 터널 요금제를 공개하지 않습니다. 변경 사항이 있으면 현재 OpenAI 문서를 확인하세요.

3. 클론 및 설치 프로그램 실행

git clone https://github.com/alexcodeplace/chatgpt-mcp.git
cd chatgpt-mcp
./install.sh

설치 프로그램은:

• 아직 제공되지 않은 경우 터널 ID와 런타임 API 키를 요청합니다;

• 두 값을 .secrets/ 아래에 보호합니다;

• 쓰기 가능한 /usr/bin Corepack 심(shim) 없이 프로젝트 고정 pnpm 11.20.0을 획득합니다;

• 의존성을 설치하고 전체 프로젝트 게이트를 실행합니다;

• 광범위 제어 템플릿에서 config.local.json을 생성합니다;

• 지원되는 Linux 아키텍처에서 누락된 경우 공식 OpenAI tunnel-client를 설치합니다;

• 필요한 경우 Debian/Ubuntu에 일반적인 데스크톱 헬퍼를 설치합니다;

• chatgpt-computer 터널 프로필을 초기화합니다;

• 임시 루프백 헬스 포트를 사용하여 포트 8080의 기존 서비스가 설치를 차단하지 않도록 합니다;

• tunnel-client doctor --explain을 실행합니다;

• ~/.config/systemd/user/chatgpt-mcp-tunnel.service를 설치하고 시작합니다;

• 서비스 및 터널 진단을 검증합니다.

비대화형 설정도 지원됩니다:

export CONTROL_PLANE_TUNNEL_ID='tunnel_0123456789abcdef0123456789abcdef'
export CONTROL_PLANE_API_KEY='sk-...'
./install.sh --yes

API 키를 ./install.sh ... 명령줄에 직접 넣거나 Git에 커밋하지 마십시오.

선택적 데스크톱 패키지 설치를 건너뛰려면:

./install.sh --no-desktop

4. ChatGPT에 추가

터널 서비스가 실행되는 동안:

1. ChatGPT 웹에서 Settings → Security and login → Developer mode를 열고 활성화합니다.

2. https://chatgpt.com/plugins 를 엽니다.

3. 더하기 버튼을 선택하고 개발자 모드 앱을 생성합니다.

4. Connection에서 Tunnel을 선택합니다.

5. 생성한 터널을 선택하거나, 제공될 때 tunnel_id를 붙여넣습니다.

6. 대화에서 새 앱을 활성화합니다.

7. 첫 테스트: Use my computer MCP's system.info tool and report the hostname and enabled capabilities.

터널이 목록에 없으면 ChatGPT 워크스페이스 연결과 Tunnels Read + Use 권한을 확인하세요.

상태 및 제거

./scripts/tunnel-status.sh

상태 명령은 저장된 런타임 키를 자체적으로 로드하고 임시 헬스 리스너를 사용하므로, 진단 실행을 위해 CONTROL_PLANE_API_KEY를 수동으로 내보낼 필요가 없습니다.

로컬 구성/비밀을 유지하면서 영구 사용자 서비스를 제거:

./scripts/tunnel-uninstall.sh

수동 설치 / 개발

저장소는 pnpm 11.20.0을 고정합니다. Corepack은 corepack enable 없이도 정확한 버전을 강제할 수 있습니다:

git clone https://github.com/alexcodeplace/chatgpt-mcp.git
cd chatgpt-mcp
corepack pnpm@11.20.0 install
corepack pnpm@11.20.0 gate

pnpm gate는 타입 검사, 동작 테스트 및 TypeScript 빌드를 실행합니다.

Corepack을 사용할 수 없으면 npx -y pnpm@11.20.0을 대신 사용하세요.

수동 구성

cp config.example.json config.local.json
export CHATGPT_MCP_CONFIG="$PWD/config.local.json"

기본 구성은 system.info만 노출합니다. 모든 기능 계열은 config.example.json을 참조하세요. config.local.json과 .secrets/는 gitignore 처리됩니다.

의도적으로 광범위한 권한이 필요하면 config.full.example.json을 대신 복사하세요.

stdio로 시작

corepack pnpm@11.20.0 build
CHATGPT_MCP_CONFIG="$PWD/config.local.json" node dist/src/stdio.js

stdout은 MCP 프로토콜 트래픽 전용입니다. 진단은 stderr로 출력됩니다.

HTTP로 시작

corepack pnpm@11.20.0 build
CHATGPT_MCP_CONFIG="$PWD/config.local.json" corepack pnpm@11.20.0 start:http

기본 엔드포인트:

http://127.0.0.1:3210/mcp

헬스 체크:

curl http://127.0.0.1:3210/healthz

HTTP는 무상태를 유지합니다. 허용 호스트가 명시적으로 구성되지 않으면 루프백이 아닌 바인드는 거부됩니다.

신뢰 경계

• 파일시스템 작업은 순회(traversal), 형제 접두어 트릭, 심볼릭 링크 탈출을 거부하는 중앙 경로 권한 부여를 통과합니다.

• shell.exec는 암시적 sh -c 없이 직접 실행 파일 + 인자 배열 스폰을 사용합니다.

• 서비스와 애플리케이션은 호출 전에 구성된 권한에 대해 검사됩니다.

• 브라우저 스킴은 열기 전에 검증됩니다.

• 데스크톱 입력과 스크린샷은 제한된 입력/출력을 가진 별도의 옵트인 기능입니다.

전체 계약은 SPEC.md를 참조하세요.

개발

corepack pnpm@11.20.0 typecheck
corepack pnpm@11.20.0 test
corepack pnpm@11.20.0 build
corepack pnpm@11.20.0 gate

GitHub Actions는 푸시와 풀 리퀘스트에서 동일한 게이트를 실행하고 설치 프로그램 스크립트의 구문을 검사합니다.

플랫폼 제한 사항

• 구체적인 어댑터는 Linux 중심입니다.

• process.list는 ps를 사용합니다.

• service.*는 기본적으로 systemd의 systemctl을 사용합니다.

• input.*는 xdotool을 사용합니다. 네이티브 Wayland는 XWayland 또는 향후 컴포지터별 어댑터가 필요할 수 있습니다.

• screen.capture는 일반적인 Linux 스크린샷 명령을 지원합니다. 데스크톱/세션 권한은 여전히 적용됩니다.

• 자동 설치 프로그램은 Linux amd64/arm64 및 systemd 사용자 서비스를 대상으로 합니다.

• 외부 ChatGPT/터널 스모크 테스트는 운영자의 자체 OpenAI 터널 ID/런타임 자격 증명이 필요합니다. 저장소 CI는 이를 대신할 수 없습니다.

상위 참조

• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

• MCP 사양: https://modelcontextprotocol.io/specification/2026-07-28

• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels

• OpenAI tunnel-client: https://github.com/openai/tunnel-client

• OpenAI 터널 관리: https://platform.openai.com/settings/organization/tunnels

• OpenAI 런타임 API 키: https://platform.openai.com/settings/organization/api-keys

• ChatGPT Developer Mode: https://developers.openai.com/api/docs/guides/developer-mode