Stata-Kernel-Jupyter

Run Stata in VS Code / Jupyter notebooks / Quarto — with a persistent session, rich outputs, and built-in AI Agent (MCP) support.

在 VS Code / Jupyter / Quarto 中直接运行 Stata —— 常驻会话、富结果输出、内置 AI Agent（MCP）支持。

中文说明

作者 / Author：Econometric 计量经济网 · www.aistata.cn

English

Open any .ipynb, switch the kernel to Stata (Stata-Kernel-Jupyter), and write Stata code. Results — logs, graphs, and auto-rendered coefficient tables — appear inline, in a persistent Stata session (no cold start per cell).

Highlights


🚀 Persistent session	Stata launches once. Every cell runs in ~0.1–1s with full data/macro state retained across cells.
📊 Rich outputs	Full log stream, inline PNG/SVG graphs, and `e(b)/e(V)` coefficient tables auto-rendered as HTML with significance stars.
📓 Jupyter-native	Real ipykernel: code-completeness detection (`foreach`/`program`/`#delimit`), Tab completion, Shift+Tab help, interrupt support.
🪄 Magics	`%head %tail %browse %describe %sum %tab %locals %help %set %png %svg %restart` (also `*%` prefix — survives .do export) and `%%stata -g / -q` cell magic.
📄 Quarto & Markdown	One-click `.do → .ipynb` and `.ipynb → .qmd` conversion; run ```{stata} chunks in `.qmd`/`.md` via CodeLens; export HTML (Quarto CLI preferred).
🤖 AI Agent ready	Built-in MCP server (`stata_run` / `stata_help` / `stata_dataset`) with structured `RunResult v1` JSON + image outputs. One command registers it to Claude, Cursor, Windsurf, Cline, Roo Code, WorkBuddy and more.
🔌 Driver fallback	PyStata (Stata 17+, in-process) → resident worker (persistent process) → CLI batch. Auto-detected.
🇨🇳 中文友好	Chinese docs/UI, UTF-8 full pipeline, CN mirror install, common community commands (`reghdfe`, `esttab`, `winsor2`…) built into completion.

Quick start

Install this extension from the VS Code Marketplace.
Click the Stata 内核 item in the status bar (or run command "Stata-Kernel-Jupyter: 一键注册 Jupyter Stata 内核"). The wizard auto-detects Python, Stata, installs the kernel package and registers the Jupyter kernelspec.
Open a .ipynb → kernel picker → search Stata → run:

sysuse auto, clear
regress price mpg weight

Commands

Command	Description
`一键注册 Jupyter Stata 内核`	One-stop wizard: environment check → package install → kernelspec registration → verify
`环境体检 (doctor)`	Diagnose Stata / Python / ipykernel / Quarto availability
`把 .do 文件转换为 Notebook`	Split a .do file into notebook cells (auto-binds the Stata kernel)
`把 .ipynb 转换为 Quarto`	Convert notebook to a Quarto `.qmd`
`执行当前 .qmd/.md 中的全部 Stata 代码块`	Run all `{stata}` chunks in one session, write results back
`导出为 HTML`	Render `.qmd/.md/.ipynb` to HTML
`把 Stata MCP 注册到 AI 客户端`	Write the MCP server config to supported AI clients

Settings

Setting	Description	Default
`skj.pythonPath`	Python interpreter used to run the kernel	auto-detect
`skj.stataExe`	Stata executable path (or env `STATA_EXE`)	auto-detect
`skj.driver`	`auto` / `pystata` / `cli`	`auto`

CLI (included with the Python package)

pip install stata-kernel-jupyter[jupyter]
skj kernel install          # register the Jupyter kernel
skj doctor                  # environment check
skj run "reg y x" --json    # structured RunResult v1
skj install-agent           # register MCP to AI clients
skj quarto run paper.qmd    # execute all {stata} chunks
skj html paper.qmd          # render HTML

Requirements

Stata 16–19 (MP/SE/BE) installed locally
Python ≥ 3.9 with ipykernel (the wizard installs what is missing)
Optional: Quarto CLI for best HTML/PDF rendering

License & notes

MIT. This extension is an independent front-end; the Stata engine logic lives in the Python package stata_kernel_jupyter. Stata® is a trademark of StataCorp LLC; this project is not affiliated with StataCorp.

中文说明

打开任意 .ipynb，把内核切换为 Stata (Stata-Kernel-Jupyter)，直接写 Stata 代码。日志、图形、自动渲染的回归系数表内联显示 —— 全程使用常驻 Stata 会话（每个 cell 无冷启动）。

核心能力


🚀 常驻会话	Stata 只启动一次，每个 cell 约 0.1–1 秒出结果，数据/宏跨 cell 完整保留
📊 富输出	完整日志流、PNG/SVG 图形内嵌、`e(b)/e(V)` 自动渲染为带显著性星号的 HTML 系数表
📓 Jupyter 原生	真正的 ipykernel：代码完整性判定（foreach/program/#delimit）、Tab 补全、Shift+Tab 帮助、中断支持
🪄 Magics	`%head %browse %sum %help %restart` 等（兼容 `*%` 前缀，导出 .do 仍可跑）与 `%%stata -g/-q`
📄 Quarto/Markdown	`.do→.ipynb`、`.ipynb→.qmd` 一键转换；`.qmd/.md` 中 stata 代码块 CodeLens 一键运行；HTML 导出
🤖 AI Agent 适配	内置 MCP server（stata_run/stata_help/stata_dataset，RunResult v1 结构化 JSON + 图像）；一条命令注册到 Claude/Cursor/Windsurf/Cline/Roo Code/WorkBuddy 等
🔌 驱动降级	PyStata（17+ 进程内）→ 常驻进程 → CLI 批处理，自动探测
🇨🇳 国内化	中文文档与 UI、UTF-8 全链路、国内镜像安装、补全内置 reghdfe/esttab/winsor2 等常用社区命令

三步上手

商城安装本扩展；
点右下角状态栏 「Stata 内核」（或命令面板执行 一键注册），向导自动完成环境检测、装包、内核注册；
打开 .ipynb → 内核选择器搜 Stata → 运行代码。

sysuse auto, clear
regress price mpg weight

命令一览

命令	说明
一键注册 Jupyter Stata 内核	选环境 → 体检 Stata → 装包 → 注册 → 校验
环境体检 (doctor)	诊断 Stata / Python / ipykernel / Quarto
把 .do 文件转换为 Notebook	按空行/`* %%` 分节转成 ipynb 并自动绑定内核
把 .ipynb 转换为 Quarto	生成 `.qmd`
执行当前 .qmd/.md 中的全部 Stata 代码块	单会话顺序执行，结果回写 `-executed.qmd`
导出为 HTML	quarto CLI 优先，无则内置渲染
把 Stata MCP 注册到 AI 客户端	自动写入 8 类客户端配置

设置项

设置	说明	默认
`skj.pythonPath`	运行内核的 Python	自动探测
`skj.stataExe`	Stata 可执行文件路径（或环境变量 `STATA_EXE`）	自动探测
`skj.driver`	auto / pystata / cli	auto

环境要求

本机安装 Stata 16–19（MP/SE/BE）
Python ≥ 3.9 与 ipykernel（向导会自动安装缺失项）
可选：Quarto CLI（获得最佳 HTML/PDF 渲染）

许可与声明

MIT 许可。Stata® 是 StataCorp LLC 的商标；本项目与 StataCorp 无隶属关系，仅通过本机安装的 Stata 软件执行代码。