npm package: @paperjsx/mcp-server
Description: Model Context Protocol server for PaperJSX - Generate PDFs, DOCX, XLSX, presentations, and documents from AI agents
Author: PaperJSX
Latest version: 0.1.0

# @paperjsx/mcp-server

AI agents can reason about documents — structure a report, draft a contract, calculate an invoice, or lay out a spreadsheet — but they cannot produce the actual files. This MCP server gives Claude, Cursor, and any MCP-compatible agent the ability to generate presentations, reports, invoices, contracts, and spreadsheets as real `.pptx`, `.docx`, `.xlsx`, and `.pdf` files.

[![npm](https://img.shields.io/npm/v/@paperjsx/mcp-server)](https://www.npmjs.com/package/@paperjsx/mcp-server)
[![CI](https://github.com/paperjsx/mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/paperjsx/mcp-server/actions/workflows/ci.yml)

## Install

```bash
npm install -g @paperjsx/mcp-server
```

Or run directly:

```bash
npx @paperjsx/mcp-server
```

## Quick Start — Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paperjsx": {
      "command": "npx",
      "args": ["-y", "@paperjsx/mcp-server"],
      "env": {
        "PAPERJSX_API_KEY": "your-api-key"
      }
    }
  }
}
```

Restart Claude Desktop. Ask it to generate a presentation, invoice, report, or spreadsheet.

### DOCX-Only Mode (No API Key)

The three DOCX tools (`generate_report_docx`, `generate_contract_docx`, `generate_invoice_docx`) render locally and do not require an API key. To use only these tools, omit the `env` block:

```json
{
  "mcpServers": {
    "paperjsx": {
      "command": "npx",
      "args": ["-y", "@paperjsx/mcp-server"]
    }
  }
}
```

## Quick Start — Cursor

Add to Cursor's MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "paperjsx": {
      "command": "npx",
      "args": ["-y", "@paperjsx/mcp-server"],
      "env": {
        "PAPERJSX_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Tools

| Tool | Output | API Key | Description |
| --- | --- | --- | --- |
| `generate_presentation` | PPTX or PDF | Yes | Multi-slide presentations with 8 slide types: title, content, chart, two-column, quote, image, comparison, stats |
| `generate_report` | PDF | Yes | Markdown-to-PDF reports with cover page, table of contents, headers/footers, and page numbers |
| `generate_invoice` | PDF | Yes | Professional invoices with tax calculation, multi-currency, and regional compliance (EU, India, Brazil) |
| `generate_chart` | PDF | Yes | Data visualization PDFs with line, bar, pie, and area charts |
| `generate_report_docx` | DOCX | No | Structured reports with sections, bullet points, themes, and table of contents |
| `generate_contract_docx` | DOCX | No | Legal contracts with parties, numbered clauses, recitals, and signature blocks |
| `generate_invoice_docx` | DOCX | No | Itemized invoices with tax, shipping, and payment terms |
| `generate_spreadsheet` | XLSX | No | Generate a workbook from `@paperjsx/json-to-xlsx` document JSON and save the artifact locally |
| `validate_spreadsheet` | Text | No | Validate an existing `.xlsx` artifact or base64 workbook and return Phase 5 quality findings |
| `repair_spreadsheet` | XLSX + Text | No | Apply conservative workbook repair, save the repaired artifact, and report repair actions |
| `list_templates` | Text | No | Browse all available document templates with schemas and examples |
| `list_components` | Text | No | List available React components for custom templates |
| `render_template` | Varies | Yes | Render a custom template by ID with data |

### Local vs Cloud

**Local rendering (no network, no API key):** `generate_report_docx`, `generate_contract_docx`, `generate_invoice_docx`, `generate_spreadsheet`, `validate_spreadsheet`, `repair_spreadsheet`. These use the built-in DOCX and XLSX engines. Files never leave your machine.

**Cloud rendering (requires API key):** `generate_presentation`, `generate_report`, `generate_invoice`, `generate_chart`, `render_template`. These call the PaperJSX cloud API for PPTX and PDF generation.

## Environment Variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `PAPERJSX_API_KEY` | For cloud tools | — | API key from [paperjsx.com](https://paperjsx.com) |
| `PAPERJSX_API_URL` | No | `https://api.paperjsx.com` | API base URL (for self-hosted deployments) |
| `PAPERJSX_OUTPUT_DIR` | No | `~/PaperJSX-Output` | Directory where generated files are saved |

## What Agents Can Do

### Generate a Word Report

> "Write a Q4 performance report as a Word document with sections for revenue, customers, and product updates."

The agent calls `generate_report_docx` with structured sections. Output: a `.docx` file with headings, bullet points, and optional table of contents.

### Create an Invoice

> "Generate an invoice for 3 months of enterprise software at $4,000/month plus $600 support. Tax rate 8.875%. Send to TechCorp Ltd in New York."

The agent calls `generate_invoice` with line items, sender/recipient details, and tax rate. Output: a print-ready PDF with automatic calculations.

### Build a Presentation

> "Make a 5-slide pitch deck: title slide, problem statement, solution, market size with a bar chart, and team slide."

The agent calls `generate_presentation` with slide types and content. Output: a `.pptx` file with editable charts that opens in PowerPoint.

### Draft a Contract

> "Draft a consulting agreement between Acme Corp and Smith Consulting for 6 months at $15,000/month."

The agent calls `generate_contract_docx` with parties, clauses, and signature blocks. Output: a `.docx` with formal legal formatting.

### Generate and Repair a Spreadsheet

> "Create an Excel workbook with a revenue sheet, save it locally, validate it, and repair it if needed."

The agent calls `generate_spreadsheet` with spreadsheet document JSON, then can pass the returned artifact path into `validate_spreadsheet` or `repair_spreadsheet`. Output: a saved `.xlsx` file plus Phase 5 validation and repair summaries.

## Presentation Slide Types

The `generate_presentation` tool supports 8 slide layouts:

| Slide Type | Content | Layout |
| --- | --- | --- |
| `title` | Title + subtitle + optional background image | Centered, large type |
| `content` | Heading + bullet points + optional image | Text with optional left/right image |
| `chart` | Heading + chart data + caption | Full-width chart |
| `two_column` | Heading + left/right content | Side-by-side columns |
| `quote` | Quote text + attribution | Centered, large type |
| `image` | Heading + image + caption | Full-bleed image |
| `comparison` | Heading + labeled items | Comparison grid |
| `stats` | Heading + metrics with trends | KPI cards |

Presentation themes: `corporate`, `modern`, `minimal`, `dark`, `gradient`. Aspect ratios: `16:9`, `4:3`.

## Artifact Management

Generated files are saved to `~/PaperJSX-Output/` (or `PAPERJSX_OUTPUT_DIR`) with timestamp prefixes. Files older than 24 hours are automatically cleaned up on server startup.

## Limitations

- Node.js >= 18 required.
- PDF and PPTX tools require network access to the PaperJSX cloud API.
- Spreadsheet validation and repair currently operate on local artifact paths or base64 workbook buffers.
- The output directory must be writable by the process.
- Generated files are saved locally — the MCP server does not retain files on any remote server.

## Documentation

[paperjsx.com/docs/mcp](https://paperjsx.com/docs/mcp)

## License

MIT