MCP LaTeX 服务器

一个用于 LaTeX 文件创建、编辑、验证和编译的模型上下文协议 (MCP) 服务器。使用 FastMCP 和 Pydantic 构建，以实现类型安全、结构化的输出。

功能特性

创建：根据参数或内置模板（article, beamer, report）创建 LaTeX 文档
编辑：通过替换、插入、追加和前置操作编辑文件
读取与列出：在安全的基础目录下操作 .tex 文件
验证：语法检查 — 大括号、环境、引用、必需声明
编译：使用 pdflatex、xelatex 或 lualatex 编译为 PDF
资源：通过 latex:// URI 浏览和获取内置模板

前置要求

Python 3.11.9+
LaTeX 发行版（用于编译）：
- Windows: MiKTeX 或 TeX Live
- macOS: MacTeX (brew install --cask mactex)
- Linux: sudo apt install texlive-full (Debian/Ubuntu) 或 sudo dnf install texlive-scheme-full (Fedora)

安装

使用 uv (推荐)

git clone https://github.com/RobertoDure/mcp-latex-server
cd mcp-latex-server
uv pip install -e .

使用 pip

git clone <repository-url>
cd mcp-latex-server
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -e .

快速设置 (Windows)

python quick_setup.py

此脚本将检查 Python 版本、安装依赖项、验证服务器导入是否正确，并可选择配置 Claude Desktop。

配置

服务器使用单个环境变量：

变量	描述	默认值
`LATEX_SERVER_BASE_PATH`	所有文件操作的根目录	`.` (当前目录)

所有传递给工具的文件路径均相对于此基础目录进行解析。禁止访问该目录之外的文件。

MCP 客户端配置

Claude Desktop

添加到你的 claude_desktop_config.json：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "latex-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-latex-server",
        "run",
        "latex_server.py"
      ],
      "env": {
        "LATEX_SERVER_BASE_PATH": "/path/to/your/latex/files"
      }
    }
  }
}

VS Code (GitHub Copilot)

添加到工作区中的 .vscode/mcp.json：

{
  "servers": {
    "latex-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-latex-server",
        "run",
        "latex_server.py"
      ],
      "env": {
        "LATEX_SERVER_BASE_PATH": "${workspaceFolder}"
      }
    }
  }
}

工具

`create_latex_file`

根据参数创建新的 LaTeX 文档。

参数	类型	默认值	描述
`file_path`	`str`	必填	新 `.tex` 文件的路径
`document_type`	`article	report	book	letter	beamer	minimal`	`article`	文档类
`title`	`str`	`""`	文档标题
`author`	`str`	`""`	文档作者
`date`	`str`	`\today`	文档日期
`content`	`str`	`""`	正文内容
`packages`	`list[str]`	`[]`	额外的 LaTeX 包
`geometry`	`str`	`""`	页面设置 (例如 `margin=1in`)

`create_from_template`

从内置模板创建文档。

参数	类型	默认值	描述
`file_path`	`str`	必填	新 `.tex` 文件的路径
`template`	`article	beamer	report`	`article`	模板名称

`edit_latex_file`

编辑现有的 LaTeX 文件。

参数	类型	默认值	描述
`file_path`	`str`	必填	文件路径
`operation`	`replace	insert_before	insert_after	append	prepend`	必填	编辑操作
`new_text`	`str`	必填	插入或替换的文本
`search_text`	`str	null`	`null`	查找的文本（替换/插入操作必需）
`line_number`	`int	null`	`null`	基于 1 的行号（`search_text` 的替代方案）

`read_latex_file`

读取并返回 .tex 文件的内容。

参数	类型	默认值	描述
`file_path`	`str`	必填	文件路径

`list_latex_files`

列出目录中的所有 .tex 文件。

参数	类型	默认值	描述
`directory_path`	`str`	`.`	要搜索的目录
`recursive`	`bool`	`false`	是否递归搜索子目录

`validate_latex`

检查 LaTeX 语法：必需声明、括号匹配、环境匹配、未定义的引用。

参数	类型	默认值	描述
`file_path`	`str`	必填	文件路径

`get_latex_structure`

提取文档结构：类、标题、作者、包和章节层级。

参数	类型	默认值	描述
`file_path`	`str`	必填	文件路径

`compile_latex`

将 .tex 文件编译为 PDF（运行引擎两次以处理引用/目录）。

参数	类型	默认值	描述
`file_path`	`str`	必填	文件路径
`engine`	`pdflatex	xelatex	lualatex`	`pdflatex`	LaTeX 引擎

资源

URI	描述
`latex://templates`	列出可用的内置模板
`latex://template/{name}`	获取特定模板的内容

测试

使用 MCP Inspector 进行测试：

uv run mcp dev latex_server.py

或者运行自带的测试套件：

python test_server.py

故障排除

服务器无法启动 — 验证 Python 3.10+ (python --version) 且已安装 mcp (pip list | grep mcp)。

编译失败 — 确保 LaTeX 发行版在你的 PATH 中 (pdflatex --version)。如果缺失，请安装 MiKTeX 或 TeX Live。

“Access denied”错误 — 请求的文件路径解析到了 LATEX_SERVER_BASE_PATH 之外。请使用相对路径或调整环境变量。

Claude 无法连接 — 仔细检查 MCP 配置中的文件路径，重启 Claude Desktop，并使用 uv run mcp dev latex_server.py 进行验证。

许可证

MIT

MCP LaTeX Server