인증된 프로덕션 준비 완료 원격 Model Context Protocol (MCP) 서버로, Terminal Execution 및 Filesystem Tools를 Notion Custom Agents, Claude, Cursor, 그리고 자율 AI 에이전트에게 Streamable HTTP를 통해 제공합니다.
공식 Ngrok Node.js SDK (@ngrok/ngrok)를 통한 설정 없는 공용 터널링이 내장되어 있습니다.
⚡ Streamable HTTP Transport: Express에서 실행되는 최신 MCP 서버 구현.
🌐 Built-in Ngrok Tunnel: @ngrok/ngrok를 사용하여 단일 명령(npm run start 또는 npm run dev)으로 로컬 MCP 서버를 Notion에 노출합니다.
💻 Terminal Execution: 구성 가능한 시간 제한, 작업 디렉터리, 재귀적 프로세스 트리 종료를 지원하는 PowerShell 또는 cmd 명령 실행.
📁 Filesystem Operations: 파일 및 디렉터리 읽기, 쓰기, 이동, 나열, 상태 확인, 삭제를 위한 전체 도구 세트.
🔒 보안 및 샌드박싱:
샌드박스 모드 (FULL_ACCESS=false): 구성된 FILES_ROOT 내부로 경로를 엄격히 제한하며 경로 탐색 방어 기능을 제공합니다.
전체 호스트 모드 (FULL_ACCESS=true): 전체 호스트 자동화가 필요할 때 무제한 액세스를 제공합니다.
타이밍 안전 인증: Bearer 토큰 및 API 키에 대한 상수 시간 비교(crypto.timingSafeEqual)를 사용합니다.
Host 헤더 검증: DNS 리바인딩 및 무단 Host 헤더 스푸핑을 방지합니다.
Related MCP server: localmcpcoder
리포지토리를 클론하고 의존성을 설치합니다:
git clone https://github.com/Speedstu/notion-terminal-mcp.git
cd notion-terminal-mcp
npm install.env.example을 .env로 복사하거나 설정 스크립트를 실행합니다:
# Automated setup (generates a secure 32+ character API key)
.\setup.ps1또는 수동으로:
Copy-Item .env.example .env
# Generate a secure token:
npm run token.env 파일을 편집합니다:
# Required: Secure API Key for Notion
MCP_API_KEY=your_generated_32_char_api_key
PORT=3000
HOST=127.0.0.1
# Ngrok Public Tunnel (Optional but recommended for Notion)
NGROK_ENABLED=true
NGROK_AUTHTOKEN=your_ngrok_authtoken_here
NGROK_DOMAIN=your-static-name.ngrok-free.app
# Security & Sandboxing
FULL_ACCESS=false
FILES_ROOT=./workspace
ALLOWED_HOSTS=localhost:3000;127.0.0.1:3000;*.ngrok-free.app;*.ngrok.app;*.ngrok-free.dev# Build TypeScript
npm run build
# Start production server
npm run start핫 리로드가 포함된 개발 모드:
npm run devNGROK_ENABLED=true로 시작하면 서버는 Notion에 붙여넣을 준비가 된 연결 세부 정보를 출력합니다:
============================================================
NOTION MCP AGENT CONNECTION READY
============================================================
URL to paste into Notion: https://your-domain.ngrok-free.app/mcp
Authentication Header:
Header Name: Authorization
Header Value: Bearer <your_token>
============================================================Notion에서 Settings & members → Connections를 엽니다 (또는 Notion Agent 구성을 엽니다).
새 Custom MCP Connection을 추가합니다.
Server URL을 다음으로 설정합니다:
https://your-domain.ngrok-free.app/mcp인증을 설정합니다:
Header Name: Authorization
Header Value: Bearer <YOUR_MCP_API_KEY>
연결을 테스트합니다. Notion은 자동으로 7개의 도구(terminal_execute, file_read, file_write, file_list, file_stat, file_mkdir, file_move, file_delete)를 발견합니다.
전체 JSON 스키마, 매개변수 및 반환 유형은 AGENT_SPEC.md를 참조하세요.
도구 | 설명 |
| UTF-8 인코딩 및 시간 제한 옵션으로 PowerShell 또는 cmd 명령을 실행합니다. |
| 이름 글로브( |
| 파일을 완전히 다시 쓰지 않고 코드 또는 텍스트의 정확한 블록을 안전하게 교체합니다. |
| 대용량 파일을 위한 오프셋 페이지네이션으로 파일 내용을 읽습니다 (UTF-8 또는 Base64). |
| 파일을 생성, 덮어쓰기 또는 내용을 추가합니다 (누락된 디렉터리를 생성합니다). |
| 파일 크기와 함께 재귀적 또는 평면적으로 디렉터리 내용을 나열합니다. |
| 파일/디렉터리 메타데이터(크기, 생성/수정 타임스탬프, 모드)를 검사합니다. |
| 디렉터리를 재귀적으로 생성합니다. |
| 파일 및 디렉터리를 이동하거나 이름을 변경합니다. |
| 파일 또는 디렉터리를 안전하게 삭제합니다 (디렉터리의 경우 |
.env)변수 | 기본값 | 설명 |
| 필수 | 인증을 위한 비밀 키 (최소 32자). |
|
| HTTP 서버 포트. |
|
| 바인딩할 호스트 주소. |
|
| 시작 시 자동 ngrok 터널 생성 활성화/비활성화. |
|
| Ngrok 인증 토큰 (ngrok CLI를 통해 전역으로 구성된 경우 선택 사항). |
|
| 정적/사용자 지정 ngrok 도메인 (예: |
|
| 허용된 |
|
|
|
|
|
|
|
| 터미널 명령의 기본 시간 제한 (2분). |
|
| 최대 stdout/stderr 캡처 크기 (1 MB). |
|
| 요청당 최대 파일 읽기/쓰기 크기 제한 (10 MB). |
notion-terminal-mcp/
├── src/
│ ├── config.ts # Type-safe environment and validation
│ ├── index.ts # Server entry point & lifecycle
│ ├── server.ts # Express setup & MCP Streamable HTTP endpoint
│ ├── middleware/
│ │ ├── auth.ts # Timing-safe token authentication
│ │ └── host.ts # Host header validation
│ ├── tools/
│ │ ├── command.ts # Process tree management & execution
│ │ ├── filesystem.ts # Sandboxed filesystem CRUD operations
│ │ ├── index.ts # MCP tool registrations
│ │ └── types.ts # MCP result helpers & interfaces
│ └── tunnel/
│ └── ngrok.ts # Ngrok SDK manager & Notion connection banner
├── AGENT_SPEC.md # Technical specification for AI Agents
├── package.json
├── tsconfig.json
└── setup.ps1 # PowerShell initial setup scriptnpm run build — TypeScript를 dist/로 컴파일합니다.
npm run start — dist/index.js에서 프로덕션 서버를 실행합니다.
npm run dev — tsx watch로 개발 서버를 실행합니다.
npm run check — 파일을 생성하지 않고 TypeScript 타입을 검사합니다.
npm run token — MCP_API_KEY용 암호학적으로 안전한 무작위 토큰을 생성합니다.
보안 고려 사항 및 취약점 보고 지침은 SECURITY.md를 검토하세요.
This server cannot be deployed
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
