Toss Place MCP

向 Codex 询问实时 Toss Place POS 销售、订单、菜单供应情况、桌台、付款以及 POS 跟踪的库存信息。

Toss Place MCP 是一个开源、自托管的集成。一个小插件在 Toss POS 内部运行，并将可读的 POS 数据安全同步到你的桥接器。Codex 通过标准本地 MCP 进程或桥接器的 Streamable HTTP 端点连接。

[!IMPORTANT] 此项目集成的是 Toss Place POS，而不是 Toss Payments。Toss Payments 是未来一个独立的提供商，具有不同的 API 和授权方式。

你可以询问的内容

• “我们今晚卖了多少，不包括未结账单？”

• “晚上 8 点到午夜之间最畅销的饮品有哪些？”

• “将这个周五与上周五进行比较。”

• “按小时展示销售情况，并告诉我应该何时安排另一位调酒师。”

• “哪些产品已售罄或低于 10 件？”

• “按卡、现金和外部支付进行细分。”

• “目前哪些桌台有未结账单？”

• “给我这个编号背后的原始 Toss 订单。”

该服务器既提供原始 POS 工具，也提供有观点的分析。未结账单始终与已入账销售额分开报告。

Related MCP server: lightspeed-x

工作原理

Toss POS plugin ──signed HTTPS──▶ self-hosted bridge + database
                                      │
                         ┌────────────┴────────────┐
                         ▼                         ▼
                 local stdio MCP          Streamable HTTP MCP
                         │                         │
                         └──────────▶ Codex ◀─────┘

当 Toss POS 运行在 iPad 或门店台式机上、而 Codex 运行在另一台电脑上时，这种拆分很重要。Docker 只是部署桥接器的一种便捷方式；它不属于 MCP 协议的一部分，也不是本地开发所必需的。

当前平台状态

• 数据路径基于 Toss Place POS 插件 SDK，该 SDK 已在真实的桌面沙盒集成中成功使用。

• 完整的桌面路径——商家激活、POS 安装、一次性配对、初始同步以及 MCP 销售/库存查询——已在 macOS 上针对 Toss 测试商家完成验证。

• 该 SDK 声明支持 Windows、macOS、Android 和 iOS 设备平台。本项目尚未在 iPad Toss POS 实例上验证完整的安装流程。

• 自托管桥接器域名通常需要添加到 Toss 开发者插件的 HTTP 允许列表/ACL 中。这是主要的手动引导步骤；Toss Place 目前不通过普通的商家 OAuth 提供此集成。

• 商家目前无法自行将 GitHub 仓库安装到 Toss POS 中。拥有所需 Toss 开发者门户访问权限的人必须创建/分发 worker 插件、分配终端和商家，并在 POS 上输入服务代码。完成该人工安装后，Codex 可以引导配对和 MCP 设置。

• 只有当商家为该目录价格启用 Toss 库存跟踪时，库存数量才可用。否则，MCP 只能报告可用性和售罄状态。

要求

• Node.js 22 或更高版本

• 对于分离设备使用，需要一个可从 Toss POS 设备访问的稳定 HTTPS URL

• 能够创建或安装 Toss Place 开发者插件

• 仅当你选择容器部署时才需要 Docker 和 Docker Compose

快速开始

1. 克隆并初始化

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

生成的 .env 权限模式为 0600，并被 Git 忽略。将 TOSS_MCP_PUBLIC_URL 设置为 POS 设备可以访问的稳定 HTTPS URL。

2. 启动桥接器

本地方式：

npm run bridge

或使用 Docker：

docker compose up -d --build

在安装 POS 插件之前，为桥接器提供一个稳定的 HTTPS 主机名。推荐的方式是 Docker 加 Caddy；在 NAT 后面，持久化的 Cloudflare Tunnel 很有用。按照 docs/deployment.md 中的说明进行 DNS、防火墙、Caddyfile、隧道、验证和重启。不要通过公网明文 HTTP 发送配对或 POS 流量。

3. 构建并安装 Toss POS 插件

npm run build:plugin
npm run zip --workspace plugin

上传工件是 plugin/place-mcp-bridge.zip，Toss 入口点位于 ZIP 内的 dist/main.js。

此部分需要具有 Toss 开发者门户访问权限的人员。在 Toss 开发者门户中：

1. 创建一个具有 POS_BACKGROUND_WORKER 入口点的 POS worker 插件应用。保持其包 ID 与上传的包一致（此仓库为 place-mcp-bridge）。

2. 将你的桥接器来源（例如 https://toss-mcp.example.com）添加到应用的 HTTP ACL/允许列表。

3. 将 plugin/place-mcp-bridge.zip 上传到开发/测试轨道，然后将该版本分发或部署到测试轨道。仅上传是不够的。

4. 在应用的测试终端设置下注册 POS 终端。使用 Toss POS 中 设置 → POS 信息/软件 下显示的序列号。

5. 打开 测试商家管理，选择该商家，在 应用 表中找到 Place MCP Bridge，并将其切换为 开启。确认 Toss 报告更新成功。

6. 完全退出并重新启动 Toss POS。

7. 在 Toss POS 中，打开 设置 → 服务集成 → 使用服务代码连接，输入开发者应用显示的服务代码，并确认 Place MCP Bridge 显示为 使用中。

测试终端注册和每个商家的 应用 → 开启 开关都是必需的。识别服务代码并不意味着该 worker 已获得该商家的授权。仅当商家所有者已批准持久化的只读数据连接时，才为其启用。

有关完整的逐点击检查清单、每个阶段后的预期结果、故障诊断以及公开商家引导的限制，请参阅 docs/toss-developer-setup.md。

4. 配对 POS

在桥接器运行时：

npm run pair

在 Toss POS 插件设置中输入显示的桥接器 URL 和一次性代码。该代码在 15 分钟后过期，且只能使用一次。由此产生的连接密钥存储在 Toss 安全存储中；插件请求带有时间戳、nonce 保护，并使用 HMAC 签名。

这些字段位于 设置 → 服务集成 → Place MCP Bridge 下。保存它们，然后完全重启一次 Toss POS，以便后台 worker 加载并执行初始同步。

验证连接：

npm run doctor

首次连接会回填最多 90 天的订单。大型商家之后可以通过 refresh_pos_data MCP 工具请求其他时间范围。

5. 连接 Codex

对于本地 stdio MCP 服务器：

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

在包发布到 npm 之前，将 -- 后面的命令替换为构建后的仓库路径：

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

对于远程 Streamable HTTP，请将此添加到 ~/.codex/config.toml：

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

然后在启动 Codex 的环境中导出 TOSS_MCP_ACCESS_TOKEN。同一主机上的 Codex 桌面版、CLI 和 IDE 客户端共享此配置。请参阅官方 Codex MCP 文档。

将此仓库交给 Codex

这是面向非开发者的预期引导体验：

从该仓库安装 Toss Place MCP 服务器。将所有凭据排除在 git 之外。在本地或使用 Docker 部署桥接器，帮我分配一个稳定的 HTTPS URL，构建 Toss POS 插件 ZIP，并在需要我批准或操作 Toss 开发者门户时停下来。创建一个一次性配对代码，验证 POS 正在同步，将 MCP 添加到我的 Codex 配置中，然后向我展示今天的已入账销售额，并与未结账单分开显示。

Codex 可以执行本地安装和验证。当账户要求时，仍必须由人工完成 Toss 门户/设备相关步骤。

MCP 工具

MCP 还发布 toss-place://capabilities 和 toss-place://data-dictionary 资源，以及一个 daily-sales-review 提示词。

这不是 Toss Place SDK 中所有可调用命名空间。它涵盖了常见销售、订单、支付、菜单、桌台和库存分析所需的只读商家数据。KDS 状态、实时草稿订单、设备/UI 控件以及所有变更操作均不在 v1 范围内。SDK 覆盖矩阵 区分了完整、部分、内部和不支持的接口。

安全模型

此版本以分析为先且只读。底层 Toss SDK 包含订单、支付、现金收据和草稿订单的变更操作，但这些操作有意不作为 MCP 工具暴露。对于销售分析服务器来说，意外取消实时账单不是可接受的默认能力。

• 桥接器 API 和远程 MCP 需要长 bearer 令牌。

• POS 同步请求使用 HMAC-SHA256、时间戳和一次性 nonce。

• 配对代码经过哈希处理，有效期短，且只能使用一次。

• 通过 .gitignore 排除密钥；示例仅包含占位符。

• 桥接器默认绑定到 127.0.0.1。

• 日志不会有意包含访问令牌或插件密钥。

在将桥接器暴露到互联网之前，请阅读 SECURITY.md。

数据与指标

默认日期边界使用 Asia/Seoul。“已入账销售额”是指已完成且未取消的订单的 Toss chargePrice.chargePriceValue 之和。当前桌台账单会单独显示，即使该账单是在请求的销售范围之前打开的；它们永远不会被计为已入账销售额。原始的有符号折扣字段会被保留，因为退款和撤销会影响其符号。

请参阅 docs/api-coverage.md 和 docs/architecture.md。

数据库

默认使用 SQLite：

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

PostgreSQL 使用相同的仓库：

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

数据库包含商家销售数据和加密传输的连接密钥。请像保护其他生产环境 POS 数据一样保护它，并根据你自己的保留策略进行备份。

开发

npm install
npm run check
npm run build:all

测试使用合成测试数据。实时集成凭据必须仅通过被忽略的环境变量提供，并且正常测试套件从不需要它们。

macOS 沙盒测试应用和所有本地 POS 数据均被排除在 Git 之外。切勿将商家桥接器 URL、访问令牌、配对代码、数据库或 Toss POS 应用包复制到提交中。

路线图

• 在真实商家上验证并记录 iPad 部署

• 如果平台允许，提供经 Toss 审核/发布的插件引导

• 可配置的保留策略和增量长期回填检查点

• 在 CI 中进行 PostgreSQL 集成测试

• 为远程 MCP 端点提供可选的 OAuth

• 单独的 Toss Payments 提供商

• 仅在存在明确的批准和审计模型之后，才提供经过严格门控的运维工具

许可证和商标

MIT。Toss 和 Toss Place 是其各自所有者的商标。除非另有说明，否则此社区项目与 Toss 无关联，也未获得 Toss 认可。

Toss Place MCP

您可以向 Codex 询问实时 Toss Place POS 销售、订单、菜单供应情况、桌台、支付以及 POS 跟踪的库存。

Toss Place MCP 是一个开源、自托管的集成工具。一个小的插件在 Toss POS 内部运行，并将可读的 POS 数据安全地同步到用户的桥接器。Codex 通过标准本地 MCP 进程或桥接器的 Streamable HTTP 端点进行连接。

[!IMPORTANT] 本项目集成的不是 Toss Payments，而是 Toss Place POS。Toss Payments 是一个独立的未来提供商，具有不同的 API 和认证方式。

您可以询问的内容

• 除去未结账订单，今晚的销售额是多少？

• 从晚上8点到午夜，最畅销的酒类是什么？

• 对比一下这周五和上周五。

• 按时间段显示销售额，并告诉我需要增派一名调酒师的时间。

• 哪些商品已售罄或库存不足10件？

• 把刷卡、现金、外部支付的比例分开显示。

• 当前有哪些桌台有未结账订单？

• 显示这些数字所依据的原始 Toss 订单。

服务器同时提供原始 POS 工具和口径清晰的分析工具。当前的未结账订单始终与已确认销售额分开报告。

工作原理

Toss POS 플러그인 ──서명된 HTTPS──▶ 셀프 호스팅 브리지 + 데이터베이스
                                            │
                              ┌─────────────┴─────────────┐
                              ▼                           ▼
                       로컬 stdio MCP             Streamable HTTP MCP
                              │                           │
                              └──────────▶ Codex ◀────────┘

这种分离很重要，因为 Toss POS 可能运行在 iPad 或门店台式机上，而 Codex 可能运行在另一台电脑上。Docker 只是便捷部署桥接服务器的一种方式，并非 MCP 协议的一部分，也不是本地开发的必需品。

当前平台状态

• 数据通路是基于已成功对接真实桌面沙箱的 Toss Place POS 插件 SDK 实现的。

• 已在 macOS 上的 Toss 测试商户中验证了完整桌面通路，包括商户激活、POS 安装、一次性配对、首次同步以及 MCP 销售额/库存查询。

• SDK 声明支持 Windows、macOS、Android、iOS 设备平台。本项目尚未在 iPad Toss POS 上验证完整的安装流程。

• 通常需要将自托管桥接域名添加到 Toss 开发者插件的 HTTP 允许列表/ACL 中。这是最重要的手动接入步骤；Toss Place 目前不通过常规的商户 OAuth 提供此集成。

• 目前商户无法仅凭 GitHub 仓库直接将插件安装到 Toss POS。需要拥有相应 Toss 开发者门户权限的人员来创建/发布 Worker 插件、分配终端和商户，并在 POS 中输入服务代码。人工完成安装后，Codex 可以引导完成配对和 MCP 配置。

• 只有商户在相应目录价格上启用了 Toss 库存跟踪时，才会提供库存数量。否则，MCP 只能报告可售状态和售罄状态。

要求

• Node.js 22 或更高版本

• 如果 POS 和桥接服务器位于不同设备上，则需要 Toss POS 设备可以访问的稳定 HTTPS URL

• 能够创建或安装 Toss Place 开发者插件的权限

• 仅当选择容器部署时才需要 Docker 和 Docker Compose

快速开始

1. 克隆并初始化

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

生成的 .env 权限模式为 0600，并被 Git 忽略。请将 TOSS_MCP_PUBLIC_URL 设置为 POS 设备可以访问的稳定 HTTPS URL。

2. 启动桥接服务器

本地运行：

npm run bridge

Docker 运行：

docker compose up -d --build

在安装 POS 插件之前，请为桥接服务器指定稳定的 HTTPS 主机名。推荐使用 Docker 加 Caddy 的组合；在 NAT 后面时，持久的 Cloudflare Tunnel 会很有用。DNS、防火墙、Caddyfile、隧道、验证和重启方法请遵循 docs/deployment.md。不要通过公开的普通 HTTP 传输配对流量或 POS 流量。

3. 构建并安装 Toss POS 插件

npm run build:plugin
npm run zip --workspace plugin

上传文件为 plugin/place-mcp-bridge.zip，ZIP 内的 Toss 入口点为 dist/main.js。

此步骤需要由拥有 Toss 开发者门户权限的人员完成。请在 Toss 开发者门户中执行以下操作：

1. 创建一个使用 POS_BACKGROUND_WORKER 入口点的 POS Worker 插件应用。包 ID 必须与上传的包一致。在本仓库中，它是 place-mcp-bridge。

2. 将桥接 origin（例如 https://toss-mcp.example.com）添加到应用 HTTP ACL/允许列表。

3. 将 plugin/place-mcp-bridge.zip 上传到开发/测试轨道，然后将该版本部署到测试轨道。仅上传是不够的。

4. 在应用的测试终端设置中注册 POS 终端。请使用 Toss POS 的设置 → POS 信息/软件中显示的序列号。

5. 打开测试商户管理，选择商户，然后在应用程序表中找到 Place MCP Bridge 并将其切换为 ON。确认 Toss 显示更改成功。

6. 完全退出并重新启动 Toss POS。

7. 在 Toss POS 中打开设置 → 服务集成 → 通过服务代码连接，输入开发者应用的服务代码，并确认 Place MCP Bridge 显示为使用中。

测试终端注册和按商户设置的应用程序 → ON 开关都是必需的。识别服务代码并不代表 Worker 已获准用于该商户。请仅在商户所有者批准持续只读数据连接后启用。

完整的分步检查清单、每个步骤的预期结果、故障诊断以及常规商户接入的限制，请参阅 docs/toss-developer-setup.md。

4. 配对 POS

在桥接服务器运行的情况下，执行以下命令：

npm run pair

将显示的桥接 URL 和一次性代码输入到 Toss POS 插件设置中。代码在 15 分钟后过期，且只能使用一次。生成的连接密钥存储在 Toss 安全存储中。插件请求包含时间戳和防重放 nonce，并使用 HMAC 签名。

输入字段位于设置 → 服务集成 → Place MCP Bridge中。保存后，请完全重启一次 Toss POS，以便后台 Worker 加载并执行首次同步。

验证连接：

npm run doctor

首次连接会回填最多 90 天的订单。大型商户之后可以使用 refresh_pos_data MCP 工具请求其他时间段。

5. 连接 Codex

本地 stdio MCP 服务器：

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

在包发布到 npm 之前，请将 -- 后面的命令替换为构建后的仓库路径。

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

要使用远程 Streamable HTTP，请在 ~/.codex/config.toml 中添加以下内容：

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

然后在运行 Codex 的环境中导出 TOSS_MCP_ACCESS_TOKEN。同一主机上的 Codex 桌面端、CLI 和 IDE 客户端共享此设置。请参阅官方 Codex MCP 文档。

将此仓库交给 Codex

以下是为非开发人员设计的接入方式：

请从这个仓库安装 Toss Place MCP 服务器。不要将任何凭据提交到 Git。将桥接服务器部署到本地或 Docker，帮我指定一个稳定的 HTTPS URL，并构建 Toss POS 插件 ZIP。在我需要在 Toss 开发者门户中批准或手动操作的步骤处停下来。生成一次性配对代码，确认 POS 完成同步，然后将 MCP 添加到我的 Codex 配置中。最后，把今天的已确认销售额和当前未结账订单分开显示。

Codex 可以执行本地安装和验证。账户所需的 Toss 门户及设备步骤必须由人工亲自完成。

MCP 工具

MCP 还提供 toss-place://capabilities、toss-place://data-dictionary 资源以及 daily-sales-review 提示词。

本项目并未提供 Toss Place SDK 中所有可调用的命名空间。它支持常规销售额、订单、支付、菜单、桌台和库存分析所需的只读商户数据。KDS 状态、实时临时订单、设备/UI 控制以及所有数据变更功能均不在 v1 范围内。SDK 支持范围表中区分了完全支持、部分支持、内部使用和不支持的表面。

安全模型

此版本是分析优先的只读服务。Toss SDK 具备订单、支付、现金收据、临时订单变更功能，但我们有意不通过 MCP 工具暴露这些功能。销售分析服务器绝不能意外取消真实的未结账订单。

• 桥接 API 和远程 MCP 要求使用长 Bearer 令牌。

• POS 同步请求使用 HMAC-SHA256、时间戳和一次性 nonce。

• 配对代码以哈希形式存储、有效期短且只能使用一次。

• 机密信息通过 .gitignore 排除，示例中仅包含占位符。

• 桥接服务器默认绑定到 127.0.0.1。

• 日志中刻意不记录访问令牌或插件密钥。

在将桥接服务器暴露到互联网之前，请阅读 SECURITY.md。

数据与指标

默认日期边界使用 Asia/Seoul 时区。“已确认销售额”是已完成且未取消订单的 Toss chargePrice.chargePriceValue 总和。当前桌台订单即使开始时间早于请求的销售期间，也会单独显示，不计入已确认销售额。由于退款和取消处理可能影响符号，因此保留原始折扣字段的符号。

请参阅 docs/api-coverage.md 和 docs/architecture.md。

数据库

默认数据库为 SQLite。

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

同一存储库也可以使用 PostgreSQL。

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

数据库包含商户销售数据和加密的传输连接密钥。请像保护其他运营 POS 数据一样保护它，并按照您自己的保留策略进行备份。

开发

npm install
npm run check
npm run build:all

测试使用合成夹具。真实集成凭据只能通过被 Git 忽略的环境变量提供，并且常规测试套件不需要它们。

macOS 沙箱测试应用和所有本地 POS 数据均被 Git 排除。请勿将商户桥接 URL、访问令牌、配对代码、数据库、Toss POS 应用包复制到提交中。

路线图

• 在实际商户中验证并记录 iPad 部署

• 在平台允许的情况下，提供 Toss 审核/公开插件接入

• 可配置的保留期和增量长期回填检查点

• 在 CI 中进行 PostgreSQL 集成测试

• 远程 MCP 端点的可选 OAuth

• 独立的 Toss Payments 提供商

• 只有在明确的审批和审计模型就绪后，才谨慎地提供受限的运营工具

许可证与商标

采用 MIT 许可证。Toss 和 Toss Place 是各自所有者的商标。除非另有说明，否则此社区项目与 Toss 没有任何关联，也未获得 Toss 的认可。