内容
# Praat-MCP（Praat ↔ Claude 联动）
语音语言学分析工具 **Praat** 与 Claude 等大型语言模型（LLM）直接联动的 MCP（Model Context Protocol）服务器。
## 目录
1. [这是什么？](#1-这是什么)
2. [准备事项（一次性安装）](#2-准备事项一次性安装)
3. [文件夹构成](#3-文件夹构成)
4. [.env 文件制作（必需）](#4-env-文件制作必需)
5. [连接到 Claude Desktop](#5-连接到-claude-desktop)
6. [使用方法（实际分析）](#6-使用方法实际分析)
## 1. 这是什么？
该程序是连接语音语言学分析工具 Praat 与 Claude 等 LLM 的工具。从技术上讲，它是一个 MCP（Model Context Protocol）服务器。
### 直接使用 Praat 与使用此 MCP 的比较
Praat 本身可以进行所有分析。此 MCP 在其基础上添加了与 Claude 的对话界面，使以下部分更加便捷。
| 任务 | 直接使用 Praat | 使用此 MCP (+Claude) |
| --- | --- | --- |
| 执行分析 | 点击菜单 → 选择对象 → 直接执行命令 | 用自然语言请求，如“分析这个语音的 jitter/shimmer”→ Claude 查找并执行合适的脚本 |
| 编写/修改脚本 | 直接学习并编写 Praat 脚本语法 | 用语言描述需求，Claude 编写/修改脚本并提出建议（无需直接编码） |
| 参数设置 | 在设置窗口中直接输入值 | 对于需要详细设置的脚本，如 pitch 范围、CPPS 选项，Claude 会先询问并建议值 |
| 结果确认 | 直接打开 Info 窗口/保存的 txt 文件阅读和解释 | Claude 与用户一起阅读结果并用对话总结和解释（txt 文件保存在 result 文件夹中） |
| 图片/声音结果 | 在 Picture 窗口中绘制并单独保存 | 在对话中直接查看脚本生成的 PNG/WAV 等输出 |
| 大量批处理 | 需要直接运行无头脚本并不断查看控制台/日志 | 可以将长时间任务放到后台运行，并在需要时询问 Claude 获取任务状态（running/done/error/timeout） |
这些功能通过以下 9 个 MCP 工具实现：
- `list_praat_scripts` / `get_praat_script` / `get_praat_script_params`：探索可用脚本、查看脚本内容、确认必要参数
- `run_praat_script` / `run_praat_script_background` / `get_praat_job_status`：立即执行或后台执行脚本、查询后台任务状态
- `create_praat_script` / `update_praat_script` / `delete_praat_script`：创建、修改、删除脚本（修改/删除时自动备份）
Claude 会根据情况判断或询问用户，以决定使用哪个脚本以及如何设置参数。
## 2. 准备事项（一次性安装）
您的电脑需要安装以下两项：
| 准备事项 | 必要性 | 安装方法 |
| --- | --- | --- |
| Python 3.12.x | 程序运行环境 | https://www.python.org/ |
| uv | 包和执行工具 | https://www.0x00.kr/development/python/python-uv-simple-usage-and-example |
在 Windows 的 cmd 中执行以下命令来确认安装：
```cmd
python -V
uv -V
```
如果版本号输出正确，则表示安装成功。
## 3. 文件夹构成
在项目文件夹（例如 `C:\Users\Your-Name\Desktop\mcp-praat`）中创建以下文件夹：
- `script`：放置 Praat 脚本（`.praat`）的文件夹
- `result`：保存分析结果（`.txt`）的文件夹
```text
mcp-praat/
├─ main.py
├─ praat_analysis.py
├─ 其他各种 .py 文件...
├─ uv.lock
├─ pyproject.toml
├─ .python-version
├─ .venv/
├─ script/
└─ result/
```
## 4. .env 文件制作（必需）
在项目文件夹（`mcp-praat`）中创建 `.env` 文件。文件名为 `.env`，无扩展名。
```text
mcp-praat/
├─ main.py
├─ praat_analysis.py
├─ 其他各种 .py 文件...
├─ uv.lock
├─ pyproject.toml
├─ .python-version
├─ .env
├─ .venv/
├─ script/
└─ result/
```
`.env` 文件中应包含的变量：
| 变量 | 含义 |
| --- | --- |
| `MCP_ROOT_DIR` | 项目文件夹路径 |
| `PRAAT_EXE_DIR` | `Praat.exe` 所在文件夹路径（或 `Praat.exe` 的完整路径） |
| `SCRIPT_DIR` | `.praat` 脚本文件夹路径 |
| `RESULT_DIR` | 结果 `.txt` 保存的文件夹路径 |
在 Windows 中，由于 `\` 符号容易引起混淆，建议用引号括起来，如下例所示：
```env
MCP_ROOT_DIR="C:\Users\Your-Name\Desktop\mcp-praat"
PRAAT_EXE_DIR="C:\Program Files\Praat"
SCRIPT_DIR="C:\Users\Your-Name\Desktop\mcp-praat\script"
RESULT_DIR="C:\Users\Your-Name\Desktop\mcp-praat\result"
```
- 如果 Praat 安装在其他位置，只需修改 `PRAAT_EXE_DIR` 即可。
- 不要在 `RESULT_DIR` 中重复路径，如 `\result`。如上例所示，只需写一次即可。
## 5. 连接到 Claude Desktop
修改 Claude Desktop 的配置文件（`claude_desktop_config.json`），使其能够执行此程序。
**注意**
- `--directory` 必须填写项目文件夹的绝对路径。
- Windows 路径中的 `\` 在 JSON 字符串中需要额外转义为 `\\`。
```json
{
"mcpServers": {
"praat-mcp": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\Your-Name\\Desktop\\mcp-praat",
"run",
"main.py"
]
}
}
}
```
配置完成后，请完全退出并重新启动 Claude Desktop。
## 6. 使用方法（实际分析）
告知 Claude 音频文件的绝对路径并请求分析即可。
```text
请分析 C:\Users\Your-Name\Desktop\audio\sample.wav 这个文件。
请执行 jitter / shimmer / HNR 分析。
请显示可用的脚本列表并选择合适的脚本执行。
```
```text
请从以下路径的音频文件中提取 CPPs：
文件路径：C:\Users\Your-Name\Desktop\mcp-praat\audio
参数设置：
- Pitch Floor: 60 Hz
- Pitch Ceiling: 330 Hz
- Time Step: 0.002s
- Max Frequency: 5000 Hz
- Pre-emphasis: 50 Hz
- Smoothing: Straight, Robust
```
```text
请为 CPPs 批量分析创建 Praat 脚本。
条件：
- 处理输入文件夹中的所有 .wav 文件
- 应用 Watts et al. (2017) 标准参数
- 将结果输出为制表符分隔的文本文件
请将完成的脚本保存为 cpps_batch.praat 文件。
```
Claude 会显示结果，同时在 `result` 文件夹中保存 `.txt` 文件。
## 如何引用
如果您在研究或流程中使用 **Praat-MCP**，请按以下格式引用：
### APA（第 7 版）
> Jeong, D. H. (2026). *Praat-MCP* (Version 1.0.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20965380
### BibTeX
```bibtex
@software{praat_mcp_2026,
author = {Jeong, Do Hyeon},
title = {Praat-MCP},
month = jun,
year = 2026,
publisher = {Zenodo},
version = {v1.0.0},
doi = {10.5281/zenodo.20965380},
url = {[https://doi.org/10.5281/zenodo.20965380](https://doi.org/10.5281/zenodo.20965380)}
}
## 免责声明
*Praat* 是由阿姆斯特丹大学的 Paul Boersma 和 David Weenink 开发的语音学软件。**Praat-MCP** 是一个独立的第三方分析流程，不官方 affiliated 或 endorsed 由原始 Praat 作者。
