Skip to main content
Glama
deenesjakoruzh
Glebsky

Notion Terminal MCP

by Glebsky
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Notion Terminal MCP

MCP Node.js TypeScript License: MIT

一个经过身份验证、生产就绪的远程 模型上下文协议（MCP） 服务器，通过 Streamable HTTP 为 Notion 自定义代理、Claude、Cursor 和自主 AI 代理提供 终端执行 和 文件系统工具。

内置通过官方 Ngrok Node.js SDK（@ngrok/ngrok）实现的零配置公共隧道。

功能特性

  • ⚡ Streamable HTTP 传输：基于 Express 的现代 MCP 服务器实现。

  • 🌐 内置 Ngrok 隧道：使用 @ngrok/ngrok 通过一条命令（npm run start 或 npm run dev）将本地 MCP 服务器暴露给 Notion。

  • 💻 终端执行：执行 PowerShell 或 cmd 命令，支持可配置超时、工作目录和递归进程树终止。

  • 📁 文件系统操作：提供完整的工具集，用于读取、写入、移动、列出、查看状态和删除文件及目录。

  • 🔒 安全与沙箱：

    • 沙箱模式（FULL_ACCESS=false）：在配置的 FILES_ROOT 内进行严格路径限制，并具备路径遍历防御。

    • 完全主机模式（FULL_ACCESS=true）：当您需要完整主机自动化时，提供无限制访问。

    • 时序安全认证：对 Bearer 令牌和 API 密钥进行恒定时间比较（crypto.timingSafeEqual）。

    • Host 头验证：防止 DNS 重绑定和未经授权的 Host 头欺骗。

  • 🤖 代理优先设计：为 AI 模型优化的详细规范和 JSON 模式（AGENT_SPEC.md）。

快速开始

1. 安装

克隆仓库并安装依赖：

git clone https://github.com/Speedstu/notion-terminal-mcp.git
cd notion-terminal-mcp
npm install

2. 环境设置

复制 .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

3. 构建与运行

# Build TypeScript
npm run build

# Start production server
npm run start

开发模式（热重载）：

npm run dev

当以 NGROK_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 自定义代理

  1. 在 Notion 中，打开 设置与成员 → 连接（或打开您的 Notion 代理配置）。

  2. 添加新的 自定义 MCP 连接。

  3. 将 服务器 URL 设置为：

    https://your-domain.ngrok-free.app/mcp

  4. 设置 认证：

    • 头名称：Authorization

    • 头值：Bearer <YOUR_MCP_API_KEY>

  5. 测试连接。Notion 将自动发现所有 7 个工具（terminal_execute、file_read、file_write、file_list、file_stat、file_mkdir、file_move、file_delete）。

可用的 MCP 工具

有关完整的 JSON 模式、参数和返回类型，请参阅 AGENT_SPEC.md。

工具

描述

terminal_execute

执行 PowerShell 或 cmd 命令，支持 UTF-8 编码和超时选项。

file_search

按名称通配符（*.ts）搜索文件，和/或在文件内搜索文本/正则表达式（Grep）。

file_replace

安全地替换文件中的精确代码块或文本，而无需完全重写。

file_read

读取文件内容（UTF-8 或 Base64），支持大文件的分页偏移。

file_write

创建、覆盖或追加内容到文件（自动创建缺失的目录）。

file_list

递归或扁平列出目录内容，包含文件大小。

file_stat

检查文件/目录元数据（大小、创建/修改时间戳、模式）。

file_mkdir

递归创建目录。

file_move

移动或重命名文件和目录。

file_delete

安全删除文件或目录（目录需要 recursive: true）。

配置参考（.env）

变量

默认值

描述

MCP_API_KEY

必填

用于认证的密钥（至少 32 个字符）。

PORT

3000

HTTP 服务器的端口。

HOST

127.0.0.1

绑定的主机地址。

NGROK_ENABLED

false

启动时是否自动创建 ngrok 隧道。

NGROK_AUTHTOKEN

""

Ngrok 认证令牌（如果已通过 ngrok CLI 全局配置，则可选）。

NGROK_DOMAIN

""

静态/自定义 ngrok 域名（例如 xyz.ngrok-free.app）。

ALLOWED_HOSTS

localhost:3000;...

允许的 Host 头列表，以分号分隔。

FULL_ACCESS

false

当为 false 时，将文件操作和终端 cwd 限制在 FILES_ROOT 内。

FILES_ROOT

./workspace

当 FULL_ACCESS=false 时沙箱的基础目录。

COMMAND_TIMEOUT_MS

120000

终端命令的默认超时时间（2 分钟）。

MAX_OUTPUT_BYTES

1048576

最大 stdout/stderr 捕获大小（1 MB）。

MAX_FILE_BYTES

10485760

每次请求的最大文件读写限制（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 script

NPM 脚本

  • npm 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 installed

-
license - not tested
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • SentinelX MCP

    Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

  • emisar

    Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.

  • StremAI

    StremAI MCP: shared memory for AI coding agents. Connected agents can recall. OAuth + local stdio.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Glebsky/notion-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server