Skip to content
satware® AI OnlyOffice MCP

Installation

Prerequisites

Section titled “Prerequisites”
Requirement Version Purpose
Node.js >= 24.0.0 Runtime for the MCP server
npm >= 11 Package manager
Docker 24.0+ OnlyOffice Document Server container
Docker Compose v2 Multi-service orchestration

Install Steps

Section titled “Install Steps”

  1. Clone the repository

    Terminal window
    git clone https://gitlab.satware.com/satware/mcp/onlyoffice.git
    cd onlyoffice

  2. Install dependencies

    Terminal window
    npm ci

  3. Start OnlyOffice Document Server

    The MCP server requires a running OnlyOffice Document Builder container for document generation.

    Terminal window
    docker compose -f docker/docker-compose.yml up -d

    Verify the Document Server is healthy:

    Terminal window
    curl -f http://localhost:9980/healthcheck
    # Expected: true

  4. Build the MCP server

    Terminal window
    npm run build

    This compiles TypeScript to dist/ and builds the admin UI to dist/admin-ui/index.html.

  5. Run the tests (optional)

    Terminal window
    npm test          # Unit tests
    npm run test:int  # Integration tests (requires Docker)

Environment Variables

Section titled “Environment Variables”

Required

Section titled “Required”
Variable Description Default
ONLYOFFICE_JWT_SECRET JWT secret for OnlyOffice Document Server communication -

Optional (Common)

Section titled “Optional (Common)”
Variable Description Default
MCP_PORT HTTP server port 3847
ADMIN_PASSWORD Password for /admin UI. If unset, /admin returns 503 -
CREDENTIAL_MASTER_PASSWORD Enables credential management tools (5 additional MCP tools) -
ARTIFACTS_BASE_URL Base URL for artifact downloads (stdio mode). If unset, artifacts are returned as base64 -
CORS_ORIGINS Comma-separated allowed origins for /mcp endpoint * (dev)

See the Deployment Guide for the full environment variable reference.

Verify Installation

Section titled “Verify Installation”
Terminal window
# Start the HTTP server
npm run start:server


# Check health
curl -f http://localhost:3847/health
# Expected: {"status":"healthy","version":"1.3.0",...}

Next Steps

Section titled “Next Steps”