A document authoring and composition MCP server that provides a pipeline for document creation: Content β Processing β Output. TeXFlow transforms your ideas into typeset documents using LaTeX, Markdown, and modern document processing tools.
This server introduces collaborative editing capabilities that prevent conflicts when multiple agents (human or AI) work on the same documents:
- Change Detection: Automatically detects when documents are modified externally
- Diff Visualization: Shows unified diffs of what changed between edits
- Conflict Prevention: Refuses to overwrite external changes, protecting everyone's work
- AI-to-AI Collaboration: Enables multiple AI agents to work together on documents without conflicts
TeXFlow enables MCP-compatible AI clients (Claude Desktop, Dive AI, or custom implementations) to have document workflow capabilities with project-based organization. Your AI assistant becomes a document authoring companion that can:
- Create and manage document projects with organized structure
- Author content in Markdown or LaTeX with proper project context
- Transform documents through a sophisticated processing pipeline
- Generate beautiful PDFs with professional typography
- Print or export documents in various formats
# Create a new document project
create_project("my-paper", "article")
# Created project 'my-paper' at ~/Documents/TeXFlow/my-paper
# Write content (automatically saved to project)
save_markdown("# Introduction\n\nThis is my paper.", "intro.md")
# Markdown saved to project 'my-paper': content/intro.md
# Generate PDF (automatically saved to project/output/pdf/)
markdown_to_pdf(file_path="intro.md", output_path="intro.pdf")
# PDF saved to project 'my-paper': output/pdf/intro.pdf
# Switch between projects
use_project("thesis-2024")
list_projects() # See all your document projects
TeXFlow's tools are organized into 9 semantic operations for easier discovery and use:
- π Document - Create, edit, convert, and validate documents
- π¨οΈ Output - Print and export to various formats
- π Project - Organize work into logical units
- π Discover - Find documents, fonts, and resources
- π¦ Organizer - Archive, move, clean documents and auxiliary files
- π¨οΈ Printer - Manage printing hardware
- π‘ Workflow - Get guidance and automation
- π Templates - Start from pre-built document templates
- π Reference - LaTeX documentation search and help
See Tool Reference for detailed documentation of all tools.
- Create organized document projects with templates (article, thesis, letter)
- Automatic project structure with content/, output/, and assets/ directories
- Switch between projects seamlessly
- Project-aware file paths for better organization
- All documents in one project stay together
- List available CUPS printers with status information
- Print plain text directly
- Print Markdown documents (rendered to PDF via pandoc)
- Print files from the filesystem
- Automatic file type detection
- Convert Markdown to PDF without printing
- Save Markdown content to .md files
- Save LaTeX content to .tex files
- Print LaTeX documents with full XeLaTeX compilation
- Smart path handling with Documents folder default
- Automatic file renaming to avoid overwrites
- Get detailed printer information
- Set default printer
- Enable/disable printers
- Update printer descriptions and locations
- Read documents with line numbers for precise editing
- Make targeted edits with string replacement and validation
- Track external changes with modification time and content hashing
- Show diffs when documents are edited outside the AI session
- Prevent conflicts between multiple editors (human or AI)
- Check document status to see what changed since last read
- Enable safe concurrent editing workflows
- Archive (soft delete) documents to hidden .texflow_archive folder
- List and browse archived documents
- Restore archived documents to original or new location
- Find versions of a document (current and archived)
- Bulk cleanup with pattern matching (e.g., archive _old files)
- Preserves document history with timestamps
- Dependency checking at startup
- Conditional tool registration based on available dependencies
- Clear feedback when dependencies are missing
- Automatic file type detection and appropriate handling
- Linux system with CUPS installed
- Python 3.10+
-
pandoc
- For markdown to PDF conversion- Debian/Ubuntu:
apt install pandoc
- Fedora:
dnf install pandoc
- Arch:
pacman -S pandoc
- Debian/Ubuntu:
-
weasyprint
- For HTML to PDF conversion- Debian/Ubuntu:
apt install weasyprint
- Fedora:
dnf install weasyprint
- Arch:
pacman -S python-weasyprint
- Debian/Ubuntu:
-
rsvg-convert
- For SVG to PDF conversion- Debian/Ubuntu:
apt install librsvg2-bin
- Fedora:
dnf install librsvg2-tools
- Arch:
pacman -S librsvg
- Debian/Ubuntu:
-
LaTeX/XeLaTeX - For PDF generation from markdown and LaTeX documents
Core Requirements:
- XeLaTeX engine for PDF compilation
- Latin Modern fonts for proper text rendering
- Standard LaTeX packages for document formatting
Installation by Distribution:
-
Debian/Ubuntu:
# Essential packages apt install texlive-xetex texlive-fonts-recommended texlive-latex-recommended # For TikZ diagrams and graphics (if needed) apt install texlive-pictures # For LaTeX validation (chktex) apt install chktex
-
Fedora:
# Essential packages dnf install texlive-xetex texlive-collection-fontsrecommended # For TikZ diagrams and graphics (if needed) dnf install texlive-collection-pictures # For LaTeX validation (chktex) dnf install texlive-chktex
-
Arch:
# Essential packages pacman -S texlive-xetex texlive-fontsrecommended # For TikZ diagrams and graphics (if needed) pacman -S texlive-pictures # For LaTeX validation (chktex) pacman -S texlive-binextra
What Each Package Provides:
texlive-xetex
: XeLaTeX engine and fontspec packagetexlive-fonts-recommended
: Latin Modern, Computer Modern, and other standard fontstexlive-latex-recommended
: Essential LaTeX packages (geometry, etc.)texlive-pictures
: TikZ package for creating diagrams and graphicschktex
/texlive-binextra
: LaTeX validation tools for checking syntax
The server checks for these dependencies at startup and enables features that have their requirements met. Missing dependencies are reported with installation instructions.
# Install system dependencies (choose your distribution)
# Debian/Ubuntu - Full installation with all features
sudo apt-get install cups pandoc texlive-xetex texlive-fonts-recommended \
texlive-latex-recommended texlive-pictures chktex \
weasyprint librsvg2-bin
# Fedora - Full installation with all features
sudo dnf install cups pandoc texlive-xetex texlive-collection-fontsrecommended \
texlive-collection-pictures texlive-chktex \
weasyprint librsvg2-tools
# Arch - Full installation with all features
sudo pacman -S cups pandoc texlive-xetex texlive-fontsrecommended \
texlive-pictures texlive-binextra \
python-weasyprint librsvg
# Clone and install
git clone https://github.com/aaronsb/texflow-mcp
cd texflow-mcp
uv sync
No installation needed! Just ensure you have uv
installed and run:
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run TeXFlow directly from GitHub
uvx --from git+https://github.com/aaronsb/texflow-mcp.git texflow
# Clone the repository
git clone https://github.com/aaronsb/texflow-mcp
cd texflow-mcp
# Run the server
uv run texflow
TeXFlow provides 9 semantic tools that intelligently guide your document workflow:
# Create with auto-format detection
document(action="create", content="# My Paper", intent="research")
# Convert existing files (don't recreate!)
document(action="convert", source="notes.md", target_format="latex")
# Edit with conflict detection
document(action="edit", path="paper.tex", old_string="draft", new_string="final")
# Print existing file (preferred)
output(action="print", source="report.pdf")
# Export to PDF
output(action="export", source="notes.md", output_path="notes.pdf")
# Create project with AI-guided structure
project(action="create", name="thesis", description="PhD thesis on quantum computing")
# Switch projects
project(action="switch", name="thesis")
printer(action="list") # Show all printers
printer(action="set_default", name="Office_Laser")
discover(action="documents", folder="drafts") # Find documents
discover(action="fonts", style="serif") # Browse fonts
archive(action="versions", filename="paper.tex") # Find all versions
archive(action="cleanup", pattern="*_old*") # Clean old files
workflow(action="suggest", task="write paper with citations")
workflow(action="next_steps") # What to do next
Each tool provides hints for next steps, guiding you through complex workflows.
For detailed documentation of all 9 tools, see Tool Reference.
For users still using individual tools, the original tool documentation follows below. Note that the unified semantic tools above are the recommended approach.
Prints plain text content.
{
"name": "print_text",
"arguments": {
"content": "Hello, World!",
"printer": "Brother_HL_L2350DW" // optional
}
}
Prints Markdown content rendered as PDF via pandoc and XeLaTeX.
Supports:
- Standard markdown formatting (headers, lists, tables, code blocks)
- LaTeX math expressions (inline with
$
, display with$$
) - Latin scripts including European languages
- Greek and Cyrillic alphabets
- Basic symbols and punctuation
Limited support for:
- Complex Unicode (emoji, box drawing characters)
- Right-to-left scripts (Arabic, Hebrew)
- CJK characters (Chinese, Japanese, Korean)
{
"name": "print_markdown",
"arguments": {
"content": "# My Document\n\nThis is **bold** text.\n\nMath: $E = mc^2$",
"printer": "HP_LaserJet", // optional
"title": "My Document" // optional
}
}
Prints a file from the filesystem.
{
"name": "print_file",
"arguments": {
"path": "/path/to/document.pdf",
"printer": "Canon_PIXMA" // optional
}
}
Get detailed information about a specific printer including status, make/model, location, and URI.
{
"name": "get_printer_info",
"arguments": {
"printer_name": "My_Printer"
}
}
Change the default printer.
{
"name": "set_default_printer",
"arguments": {
"printer_name": "CanonG3260"
}
}
Control printer availability for accepting jobs.
{
"name": "enable_printer",
"arguments": {
"printer_name": "My_Printer"
}
}
Update printer description and/or location.
{
"name": "update_printer_info",
"arguments": {
"printer_name": "My_Printer",
"description": "Office Color Laser",
"location": "Room 201"
}
}
Convert markdown to PDF and save to a file (without printing).
Supports:
- Same markdown features as
print_markdown
- Saves PDF to specified path instead of printing
{
"name": "markdown_to_pdf",
"arguments": {
"content": "# My Document\n\nSave this as PDF.",
"output_path": "report.pdf", // Saves to ~/Documents/report.pdf by default
"title": "My Document"
}
}
Print LaTeX content (compiled to PDF via XeLaTeX).
Supports:
- Full LaTeX syntax and packages
- Mathematical formulas and equations
- TikZ diagrams and graphics
- Bibliography and citations
- Custom document classes
{
"name": "print_latex",
"arguments": {
"content": "\\documentclass{article}\n\\begin{document}\nHello LaTeX!\n\\end{document}",
"printer": "My_Printer", // optional
"title": "My LaTeX Doc" // optional
}
}
Save markdown content to a .md file.
{
"name": "save_markdown",
"arguments": {
"content": "# My Document\n\nThis is my markdown content.",
"filename": "notes.md" // Saves to ~/Documents/notes.md by default
}
}
Save LaTeX content to a .tex file.
{
"name": "save_latex",
"arguments": {
"content": "\\documentclass{article}\n\\begin{document}\nHello LaTeX!\n\\end{document}",
"filename": "document.tex" // Saves to ~/Documents/document.tex by default
}
}
List PDF and Markdown files in the Documents folder.
{
"name": "list_documents",
"arguments": {
"folder": "reports" // Optional: list files in ~/Documents/reports
}
}
Print a PDF or Markdown file from the Documents folder.
{
"name": "print_from_documents",
"arguments": {
"filename": "report.pdf", // or just "report" - will find .pdf or .md
"printer": "My_Printer", // optional
"folder": "reports" // optional subfolder
}
}
Features:
- Automatically finds .pdf or .md extension if not specified
- Converts Markdown files to PDF before printing
- Works with subfolders in Documents
Convert a Markdown file to LaTeX format for further customization.
{
"name": "markdown_to_latex",
"arguments": {
"file_path": "research_notes.md", // Path to markdown file
"output_path": "research_paper.tex", // Optional: output path
"title": "My Research Paper", // Optional: document title
"standalone": true // Optional: create complete document (default: true)
}
}
Features:
- Converts Markdown to editable LaTeX format
- Preserves math expressions, tables, and formatting
- Adds conversion metadata as comments
- Allows fine-tuning before final PDF compilation
- Part of the markdown β LaTeX β PDF workflow
Workflow example:
1. save_markdown(content="...", filename="notes.md")
2. markdown_to_latex(file_path="notes.md") # Creates notes.tex
3. edit_document(file_path="notes.tex", ...) # Optional: customize
4. latex_to_pdf(file_path="notes.tex", output_path="final.pdf")
List fonts available for use with XeLaTeX documents.
{
"name": "list_available_fonts",
"arguments": {
"style": "serif" // Optional: filter by 'serif', 'sans', 'mono', or None for all
}
}
Features:
- Lists all system fonts compatible with XeLaTeX
- Filter by font style (serif, sans-serif, monospace)
- Groups fonts alphabetically for easy browsing
- Provides usage examples for LaTeX documents
- Shows popular font recommendations
Validate LaTeX content for syntax errors before compilation.
{
"name": "validate_latex",
"arguments": {
"content": "\\documentclass{article}\n\\begin{document}\nHello!\n\\end{document}"
}
}
Features:
- Uses
lacheck
andchktex
for syntax checking (if available) - Performs test compilation with XeLaTeX
- Returns detailed error reports and warnings
- Helps catch errors before printing
Read a document file with line numbers for editing.
{
"name": "read_document",
"arguments": {
"file_path": "proposal.tex", // or full path
"offset": 1, // starting line (optional, default: 1)
"limit": 50 // number of lines (optional, default: 50)
}
}
Features:
- Returns content with line numbers in
cat -n
format - Works with any text file in Documents folder
- Smart path handling (defaults to ~/Documents/)
- Supports reading portions of large files
Edit a document file by replacing exact string matches.
{
"name": "edit_document",
"arguments": {
"file_path": "proposal.tex",
"old_string": "Hello World",
"new_string": "Hello CUPS MCP",
"expected_replacements": 1 // optional, default: 1
}
}
Features:
- Exact string replacement with occurrence validation
- Returns context snippet showing changes
- Prevents accidental replacements with count validation
- Same smart path handling as read_document
- Collaborative editing support: Detects external file changes and shows diffs
- Prevents overwrites when user has edited file externally
- Automatically tracks file modifications for safe concurrent editing
Check if a document has been modified externally and show changes.
{
"name": "check_document_status",
"arguments": {
"file_path": "proposal.tex" // or full path
}
}
Features:
- Tracks document modification times and content hashes
- Detects external changes made by users or other programs
- Shows unified diff of what changed since last read
- Helps coordinate collaborative editing between AI and users
- Essential for preventing conflicting edits in shared documents
Path handling for save tools:
- Simple filename (e.g.,
report.pdf
) β Saves to~/Documents/
- Full path (e.g.,
/home/user/Documents/report.pdf
) β Uses exact path - Path with
~
(e.g.,~/Downloads/report.pdf
) β Expands to home directory
Automatic features:
- Creates Documents directory if it doesn't exist
- Generates unique filename if file already exists (adds _1, _2, etc.)
- Returns clear error messages for permission issues or other failures
When using the printing tools, AI agents should follow this logic:
-
First print request:
- If user doesn't specify, ask: "Would you like to print or save as PDF?"
- If printing and no default printer exists, ask which printer to use
- Remember the chosen printer for the session
-
Subsequent requests:
- Use the remembered printer from the first request
- Only change if user explicitly specifies a different printer
When saving PDFs with markdown_to_pdf
:
- Use simple filenames (e.g.,
report.pdf
) which save to~/Documents/
- Don't assume the user's home directory path
- Let the tool handle path expansion
This ensures users aren't repeatedly asked about printer selection and files are saved to predictable locations.
TeXFlow requires a workspace path where all your document projects will be stored. This is passed as the last argument to the texflow
command.
Claude Desktop uses a JSON configuration file to manage MCP servers. The location depends on your operating system:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
Add this to your claude_desktop_config.json
:
{
"mcpServers": {
"texflow": {
"command": "uvx",
"args": ["--from", "git+https://github.com/aaronsb/texflow-mcp.git", "texflow", "/home/aaron/Documents/TeXFlow"]
}
}
}
Note: Replace /home/aaron/Documents/TeXFlow
with your desired workspace path.
If you've cloned the repository locally:
{
"mcpServers": {
"texflow": {
"command": "uv",
"args": ["--directory", "/path/to/texflow-mcp", "run", "texflow", "/home/aaron/Documents/TeXFlow"]
}
}
}
Note: Replace /path/to/texflow-mcp
with the actual path to your cloned repository.
After editing the config file, restart Claude Desktop for the changes to take effect.
Claude Code provides a CLI command to add MCP servers. You can choose between different scopes:
--scope user
: Available across all your projects (recommended)--scope project
: Only available in the current project--scope local
: Available only on this machine
# Add with user scope (available in all projects)
claude mcp add --scope user texflow uvx -- --from git+https://github.com/aaronsb/texflow-mcp.git texflow ~/Documents/TeXFlow
# Or with project scope (current project only)
claude mcp add --scope project texflow uvx -- --from git+https://github.com/aaronsb/texflow-mcp.git texflow ~/Documents/TeXFlow
If you've cloned the repository:
# Add with user scope
claude mcp add --scope user texflow uv -- --directory /path/to/texflow-mcp run texflow ~/Documents/TeXFlow
# Or with project scope
claude mcp add --scope project texflow uv -- --directory /path/to/texflow-mcp run texflow ~/Documents/TeXFlow
Note: The --
after the scope is required to separate Claude Code options from the command arguments.
You can specify the workspace path in three ways:
- Command line argument:
~/Documents/TeXFlow
as shown in the examples above - Environment variable: Set
TEXFLOW_WORKSPACE=~/Documents/TeXFlow
in your shell or system environment - Default: If neither is provided, defaults to
~/Documents/TeXFlow
All TeXFlow projects and documents will be created within this workspace directory.
After installation, you can verify TeXFlow is working by asking Claude to:
- List available TeXFlow projects: "Use texflow to list my projects"
- Check system dependencies: "Check texflow system dependencies"
- Create a test project: "Create a new texflow project called 'test'"
The collaborative editing features enable fascinating multi-agent workflows:
- Parallel Document Development: Multiple AI agents can work on different sections simultaneously
- Review Workflows: One AI drafts, another reviews and edits
- Specialized Collaboration: Domain-specific AIs (e.g., technical writer + code reviewer) working together
- Iterative Refinement: AIs can build upon each other's contributions with full visibility
- Agent A reads and edits a document, establishing a baseline
- Agent B detects Agent A's changes through the diff system
- Agent B reviews the changes before making its own contributions
- Each agent maintains awareness of others' modifications through the tracking system
# Agent 1 (Technical Writer AI)
- Creates initial documentation structure
- Writes API reference sections
# Agent 2 (Code Examples AI)
- Detects Agent 1's additions
- Adds code examples to each API section
- Preserves Agent 1's documentation
# Agent 3 (Review AI)
- Sees combined work from both agents
- Fixes inconsistencies
- Adds cross-references
This opens up entirely new possibilities for AI collaboration on complex documentation and content creation tasks.
# Create project structure
project(action="create", name="ml-paper", description="Machine learning research paper")
# Create bibliography
document(action="create", content="@article{smith2023,...}", path="refs.bib")
# Create main document
document(action="create", content="\\documentclass{article}...", path="paper.tex")
# Export to PDF
output(action="export", source="paper.tex", output_path="paper.pdf")
# Convert existing Markdown notes to LaTeX
document(action="convert", source="notes.md", target_format="latex")
# Edit the converted file
document(action="edit", path="notes.tex", old_string="TODO", new_string="Introduction")
# Generate PDF
output(action="export", source="notes.tex")
The system prevents common AI workflow issues:
- Smart Content Detection: The server detects when LaTeX content has already been saved and warns against regenerating it
- Clear Tool Guidance: Tool descriptions guide the preferred workflow (save β use file path)
- Better Error Handling: LaTeX error parser provides specific package installation instructions
Example of the improved workflow:
# Step 1: Save LaTeX content
save_latex(content="...", filename="paper.tex")
# Returns: "LaTeX saved successfully to: /home/user/Documents/paper.tex"
# Step 2: Convert to PDF using file path (not content!)
latex_to_pdf(file_path="/home/user/Documents/paper.tex", output_path="paper.pdf")
# Efficient: Uses saved file instead of regenerating content
- π Tool Reference - Complete guide to all 9 semantic tools
- π€ Collaborative Editing Guide - Deep dive into collaboration features
- π― LaTeX Reference Design - Design of the LaTeX documentation tool
- π System Dependencies - System requirements and dependency management
- π¨βπ³ Recipe Book Example - Practical example creating a recipe book
- π Complete Workflow Example - End-to-end workflow examples
- HTML to PDF printing (via weasyprint)
- SVG to PDF printing (via rsvg-convert)
- Image format handling and scaling
- Print job status tracking
- Print job cancellation
- Printer options (paper size, orientation, etc.)
- Base64 encoded content support
MIT