Set API_KEY in your .env to require an API key for all requests:

API_KEY=your-secret-key

Clients can send the key in any of these headers:

Leave API_KEY empty or unset to allow all requests without authentication.

Set UPLOAD_STRATEGY=S3 and provide:

Credential modes:

• Explicit credentials — Set all three of AWS_ACCESS_KEY, AWS_SECRET_ACCESS_KEY, and AWS_REGION. Recommended for simple setups.

• AWS default credential chain — Leave the credential variables unset and boto3 will automatically discover credentials from the standard chain:

  • AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables
  • Shared credential / config files (~/.aws/credentials)
  • AWS SSO sessions (aws sso login) — useful for local development
  • IRSA (IAM Roles for Service Accounts) — for AWS EKS deployments
  • ECS container credentials / EC2 instance metadata (IMDSv2)

  In this mode only S3_BUCKET is required; region is resolved automatically.

Set UPLOAD_STRATEGY=GCS and provide:

Mount the credentials file via docker-compose.yml volumes.

Set UPLOAD_STRATEGY=AZURE and provide:

Set UPLOAD_STRATEGY=MINIO and provide:

Make sure the bucket exists and your credentials have PutObject/GetObject permissions.

The server exposes health-check endpoints that Kubernetes (or any orchestrator) can use for liveness/readiness probes:

Thread-pool offloading: By default (RUN_BLOCKING_BY_ASYNCIO_THREAD_ENABLED=true), all blocking document-generation work is dispatched to a bounded thread pool (RUN_BLOCKING_MAX_WORKERS threads, default 4). This keeps the asyncio event loop free to respond to health probes and handle concurrent requests — critical for Kubernetes deployments where blocked probes lead to pod restarts.

Set RUN_BLOCKING_BY_ASYNCIO_THREAD_ENABLED=false only for local debugging or to rule out threading-related issues.

Tool parameters (create_word_from_markdown):

Block elements (each on its own line, separated by blank lines):

⚠️ Don't confuse --- (page break) with *** (horizontal line).

💡 A single numbered line is only treated as a list when it starts at 1. or is followed by another item. This means a standalone date like 23. června 2026 renders as plain text, not a list. The one exception is a day-1 date (1. června 2026), which is indistinguishable from a one-item list — escape the dot to keep it as text: 1\. června 2026.

Inline formatting (works in paragraphs, headings, list items, table cells, quotes):

Nesting and combinations work, e.g. **bold with *italic* inside**, **~~bold strikethrough~~**.

Table features — place the directive on the line directly above the table:

Text alignment (HTML tags, single- or multi-line):

<center>centered text</center>
<div align="right">right-aligned</div>
<div align="justify">justified paragraph…</div>

Soft line break: end a line with two trailing spaces to break within the same paragraph.

Custom styles (issue #66) — remap built-in styles or apply an ad-hoc one:

<!-- style: Callout -->
This paragraph uses the "Callout" style from your template.

The <!-- style: Name --> directive applies a style to the next block only — one paragraph, one heading, the whole table, or the top-level items of a list (nested items keep the List Bullet 2/3 / List Number 2/3 styles). On a numbered list the style's own numbering is used: the list restarts at 1. with the style's numeral format and indents. The directive must be alone on its line, and the name must match the Word style name exactly. Unknown styles fall back to the default with a warning. To remap styles globally or per template, see Custom Templates.

Tool parameters (create_excel_from_markdown):

Sheets & tables:

Formulas & references (put a formula in any cell, starting with =):

Column directives — place on the line directly above a table:

Column alignment via the :---: separator syntax is honored, and inline **bold** / *italic* in cells is applied as cell formatting.

1. Create config/email_templates.yaml:

templates:
  - name: welcome_email
    description: Welcome email with optional promo code
    html_path: welcome_email.html  # must be in custom_templates/ or default_templates/
    annotations:
      title: Welcome Email
    args:
      - name: first_name
        type: string
        description: Recipient's first name
        required: true
      - name: promo_code
        type: string
        description: Optional promotional code (HTML formatted)
        required: false

2. Create the HTML file in custom_templates/welcome_email.html:

<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8" /></head>
<body>
  <h2>Welcome {{first_name}}!</h2>
  <p>We're excited to have you on board.</p>
  {{{promo_code_block}}}
  <p>Regards,<br/>Support Team</p>
</body>
</html>

How it works:

• Each template becomes a separate AI tool at startup
• Standard email fields (subject, to, cc, bcc, priority, language) are added automatically
• Use {{variable}} for escaped text, {{{variable}}} for raw HTML

1. Create config/docx_templates.yaml:

templates:
  - name: formal_letter
    description: Generate a formal business letter
    docx_path: letter_template.docx  # must be in custom_templates/ or default_templates/
    annotations:
      title: Formal Letter Generator
    args:
      - name: recipient_name
        type: string
        description: Full name of the recipient
        required: true
      - name: recipient_address
        type: string
        description: Recipient's address
        required: true
      - name: subject
        type: string
        description: Letter subject
        required: true
      - name: body
        type: string
        description: Main body of the letter (supports markdown)
        required: true
      - name: sender_name
        type: string
        description: Sender's name
        required: true
      - name: date
        type: string
        description: Letter date
        required: false
        default: ""

2. Create a Word document with placeholders and save as custom_templates/letter_template.docx:

{{date}}

{{recipient_name}}
{{recipient_address}}

Subject: {{subject}}

{{body}}

{{sender_name}}

How it works:

• Each template becomes a separate AI tool at startup
• Placeholders can be in the document body, tables, headers, and footers
• Placeholder values support full Markdown (bold, italic, lists, headings…)
• The placeholder's own formatting — font, size, colour, bold, italic, underline, highlight — is captured and applied to the replacement text (markdown in the value, e.g. **bold**, still wins where it sets formatting)
• Formatting of the surrounding text in the same paragraph (before/after the placeholder) is preserved

For proper formatting, make sure these styles exist in your .docx template:

Tip: Customize these styles (font, size, color, spacing) in your template — the server will use your styling.

If your template defines styles under different names than the built-ins above, map them in config/docx_templates.yaml so rendered Markdown uses them — no need to rename styles in Word.

A top-level style_mapping: applies to every document; each template may add its own style_mapping: which overrides the global one for that template.

# config/docx_templates.yaml

# Global — applies to all conversions:
style_mapping:
  heading_1: "Brand Title"
  list_number: "Brand Numbers"
  quote: "Brand Quote"
  table: "Brand Table"

templates:
  - name: formal_letter
    docx_path: letter_template.docx
    # Per-template override (wins over the global mapping):
    style_mapping:
      quote: "Letter Quote"
    args: [ ... ]

Recognized keys: heading_1…heading_6, list_number / _2 / _3, list_bullet / _2 / _3, quote, table, normal, code (style for fenced code blocks).

Ad-hoc style tag: to apply any style to a single block without a mapping, put a directive directly above it:

<!-- style: Callout -->
This paragraph uses the "Callout" style.

Unknown style names fall back to the document default (with a logged warning) rather than failing the document.

1. Set these in your .env:

ADMIN_ENABLED=true
ADMIN_PASSWORD=choose-a-strong-password   # falls back to API_KEY if omitted
# ADMIN_PATH=/admin                        # optional, this is the default

2. Start the server as usual. The admin UI is served from the same port as the MCP endpoint:

http://localhost:8958/admin

3. Log in with your ADMIN_PASSWORD, then:

• Upload a Word .docx (or email .html) that contains {{placeholders}} (and optionally {{#if flag}} … {{/if}} conditionals). Author it in real Word — full fidelity is preserved.
• The UI auto-detects every placeholder and conditional and pre-builds the argument form. Fill in each argument's type, whether it's required, a default, and the description the AI sees.
• Preview with sample values (generates a real file; never uploaded anywhere).
• Save — the template becomes a live MCP tool immediately, no restart.
• Edit later — adjust arguments, or Replace document to upload a new version and re-scan it for placeholders (existing arguments are kept).
• Status page — see live tool counts, per-template usage (calls/errors/last used this session), and a recent activity & error log (filterable to warnings/errors).

How it's stored: the UI writes one file per template into config/docx_templates.d/ or config/email_templates.d/ (plus the asset into custom_templates/). Your hand-written master config/*.yaml files are never modified — UI templates are simply merged on top of them at load time.

Single-instance note: live, no-restart registration assumes one server instance owns the template files (the standard docker-compose setup). For a multi-replica deployment, put the template files on shared storage and roll the pods to pick up changes.

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "office-documents": {
      "url": "http://localhost:8958/mcp"
    }
  }
}

Add the server to your librechat.yaml configuration under mcpServers:

mcpServers:
  office-documents:
    type: streamableHttp
    url: http://mcp-office-docs:8958/mcp

Note: If LibreChat and this server run in the same Docker network, use the container name (mcp-office-docs) as the hostname. If they run separately, use http://localhost:8958/mcp instead.

To place both services on the same network, add a shared network in your docker-compose.yml:

services:
  mcp-office-docs:
    # ...existing config...
    networks:
      - shared

  librechat:
    # ...existing config...
    networks:
      - shared

networks:
  shared:
    driver: bridge

Use the SSE/streamable HTTP transport and set the endpoint URL to:

http://localhost:8958/mcp

If you have authentication enabled, add the API key header as required by your client.