GenFiles MCP Server

GenFiles is a local-first MCP server for generating PowerPoint, Excel, Word, and Markdown files from agent requests. It runs over streamable-http, stores outputs locally under generated_files/, and returns machine-readable download metadata for every generated file.

For a single-instance private Azure VM deployment, see Azure deployment. The root docker-compose.yml is a local example, not the Azure deployment configuration.

What You Can Do

• Generate PPTX, XLSX, DOCX, and MD files through MCP tools.

• Review existing DOCX files and write targeted comments back into a reviewed copy.

• Register catalog images over HTTP for remote clients, then reuse their asset_id values in DOCX and PPTX generation.

• Return structured results containing download_url, file_name, download_markdown, and assistant_response_markdown.

Related MCP server: docforge-mcp

Quick Start

1. Install dependencies

uv sync

2. Create .env

Copy the tracked template, then adjust values for your machine. .env is ignored by Git and is the server's local configuration source.

Copy-Item .env.example .env

3. Start the MCP server

powershell -ExecutionPolicy Bypass -File .\scripts\start_streamable_http.ps1

4. Use the default endpoints

MCP:        http://127.0.0.1:8016/mcp
Downloads:  http://127.0.0.1:8016/downloads/{filename}
Catalog:    POST http://127.0.0.1:8016/image-catalog/assets
Search:     POST http://127.0.0.1:8016/image-catalog/search
Image GET:  http://127.0.0.1:8016/images/{asset_id}
Source extract: POST http://127.0.0.1:8016/source-extract (`.xlsx`, `.docx`, `.pptx`)

5. Change configuration

Change values in .env, then restart the server. For example, set a reachable base URL for clients on another machine:

PUBLIC_BASE_URL=http://192.168.1.10:8016

Enable structured Word generation instead of Python-script Word generation:

ENABLE_WORD_ELEMENT_FILLING=true

Typical Flow

1. Start the server.

2. Connect your MCP client to http://127.0.0.1:8016/mcp.

3. Call generate_powerpoint, generate_excel, generate_markdown, or the active Word tool.

4. Download generated files from the returned download_url.

5. Register remote images with POST /image-catalog/assets and pass the returned asset_id values into the document-generation tool.

Environment Variables

server.py loads .env on startup. Values already present in the process environment take precedence, which is useful for container or deployment configuration.

Source-document extraction

Submit exactly one .xlsx, .docx, or .pptx file as multipart/form-data to POST /source-extract. The response contains bounded plain text: worksheet rows are tab-separated, DOCX paragraphs/tables are labeled, and PPTX slide text/tables are grouped by slide.

Current Image Support

• DOCX: Supports real image embedding from local image paths and permanent catalog asset_id values. Script mode accepts images_list and image_ids, and structured mode accepts image references inside document elements.

• PPTX: Supports real image embedding from local image paths and permanent catalog asset_id values. The generated script must use the preloaded images objects with add_picture(...).

• XLSX: Supports catalog asset_id values and local image paths. Images are preloaded for the generation script, which anchors each image to a cell and sets its explicit pixel size while preserving aspect ratio.

• MD: Does not embed binary images into the file. Markdown content can reference images by path or URL, but there is no dedicated image preload pipeline.

Image Catalog For Remote Clients

• Register one image at POST /image-catalog/assets using multipart/form-data with the binary field named image.

• Include purpose, prompt, description, keywords (JSON array), style, aspect_ratio, embedding (JSON number array), and source (generated or user_upload).

• Images are normalized to JPEG at quality 85, or PNG when transparency is required, with a maximum side length of 1920px.

• Exact duplicate binaries return the existing asset_id instead of storing another file.

• Search existing assets with POST /image-catalog/search, providing an embedding and optional style/aspect-ratio filters.

• Pass returned asset_id values as image_ids to generate_word, generate_powerpoint, or generate_excel. images_list remains available for same-machine local paths.

Current Limits

• Generated files are saved on the host under generated_files/ and served through /downloads/{filename}.

• Catalog images stay permanently under image_library/ and are never removed by the cleanup worker.

• Generated documents are cleaned after 7 days by default. Set GENERATED_FILE_TTL_SECONDS to adjust this value.

• If a file is deleted from the host, its download_url will return 404.

Additional setup notes live in docs/installation.md, docs/features.md, and docs/codex-plugin-streamable-http.md.