Home Original page

GitHub - kiteworks/mcp: Kiteworks MCP Server

The Kiteworks MCP Server enables Large Language Model (LLM) applications to securely interact with your Kiteworks instance through the Model Context Protocol (MCP). This cross-platform server provides AI assistants with the ability to manage files, folders, and user information within your Kiteworks environment while maintaining enterprise-grade security.

Key Capabilities:

  • File Management: Upload, download, retrieve metadata, rename, move, and delete files (single or multiple)
  • Folder Operations: Navigate hierarchies, create, rename, move, delete, and search files/folders with filtering (single or multiple)
  • Forms Creation: Generate Kiteworks Secure Data Forms from templates with preview links
  • User Information: Access current user details and authentication status
  • Dual Mode Support: Local STDIO mode for single users, Remote HTTPS mode for multi-user deployments
  • OAuth 2.1 Security: Dynamic Client Registration, Authorization Code flow with PKCE, using JWT access and refresh tokens with automatic refresh
  • FIPS 140-3 Compliance: AES-256-GCM encryption, TLS 1.3 with post-quantum hybrid key exchange (X25519+ML-KEM-768)
  • Rate Limiting: Configurable limits at global, per-user, and per-session levels
  • Cross-Platform: Native binaries for Windows, Linux, and macOS

Connection Modes:

  • Local STDIO Mode: Single-user deployment with OS keychain storage
  • Remote HTTPS Mode: Multi-user centralized server with volume storage and automatic OAuth

Security Considerations

This MCP server may handle sensitive data accessible to connected AI assistants. Only install trusted and verified MCP servers.

The Kiteworks MCP Server does not expose credentials or security tokens to the LLM. They are securely stored in your operating system encrypted keychain or encrypted credential store.

In Local STDIO mode, the Kiteworks MCP Server does not make the data it transfers available to the LLM (in the LLM context). In addition, by default absolute paths are not allowed for upload or for storing downloaded content. You will not be able to upload /etc/passwd or download to /etc/passwd. To allow absolute paths, consult the command line options.
In Remote HTTPS mode, files are transferred via the LLM context and the LLM has access to the content.

The Kiteworks MCP Server validates the TLS certificate of the remote Kiteworks server it connects to. It will abort if it can't be validated, to protect against man in the middle attacks. If your Kiteworks instance uses a self-signed certificate or a certificate from an unknown certificate authority, you can supply the Root CA chain using a command line option.

Claude Code Integration

The Kiteworks MCP Server fully supports Claude Code with automatic OAuth integration:

  • Automatic Setup: Claude Code discovers and registers with the server automatically
  • Browser Authentication: Opens browser for Kiteworks login
  • Secure Connection: Uses standard OAuth 2.1 with PKCE security and Dynamic Client Registration (DCR)
  • Multi-User Support: Each user authenticates with their own Kiteworks credentials

Documentation:

Installation & Setup in Local STDIO mode

Download the Binary

Download the latest official release for your operating system from the CI artifacts. Official builds are pre-signed for Windows and macOS.

Claude Code Integration

Windows:

claude mcp add --transport stdio kiteworks C:\Path\To\kiteworks-mcp.exe start https://your.kiteworks.domain

macOS / Linux:

claude mcp add --transport stdio kiteworks /path/to/kiteworks-mcp start https://your.kiteworks.domain

On first use, your browser will open automatically for Kiteworks authentication.

Visual Studio Code

See: VS Code MCP Servers Guide

Configuration example:

{
  "mcpServers": {
    "kiteworks": {
      "command": "/path/to/kiteworks-mcp",
      "args": ["start", "https://your.kiteworks.domain"]
    }
  }
}

MCP Inspector

Configure the connection:

  • Command: /path/to/kiteworks-mcp
  • Arguments: start https://your.kiteworks.domain
  • Transport: STDIO

Advanced Configuration

Custom CA Certificate:

kiteworks-mcp start --ca-cert /path/to/ca_chain.pem https://your.kiteworks.domain

Allow Absolute Paths (not recommended):

kiteworks-mcp start --insecure-absolute-paths https://your.kiteworks.domain

Claude Desktop Configuration:

{
  "mcpServers": {
    "kiteworks": {
      "command": "/path/to/kiteworks-mcp",
      "args": [
        "start",
        "--insecure-absolute-paths",
        "--ca-cert",
        "/path/to/ca_chain.pem",
        "https://your.kiteworks.domain"
      ]
    }
  }
}

Installation & Setup in Remote HTTPS Mode

Remote HTTPS mode is designed for multi-user deployments where multiple users and MCP clients connect to a centralized server. The server handles OAuth authentication automatically for each user.

Prerequisites

Kiteworks OAuth Application

Create a custom OAuth application in your Kiteworks Admin Console with:

  • Authorization Code flow enabled
  • Refresh Token enabled
  • Redirect URI: https://your-mcp-server.example.com:8080/oauth/callback (adjust port and domain as needed)

Required Scopes:

  • Files: CREATE, READ, UPDATE, DELETE
  • Folders: CREATE, READ, UPDATE, DELETE
  • Search: READ
  • Users: READ

Deployment Options

Option 1: Docker Container (Recommended)

Using Docker Compose:

Create the required directories, copy your TLS certificates, generate encryption keys, and configure your .env file:

mkdir -p conf data secrets
cp .env.example conf/.env
# Edit conf/.env with your configuration
# Copy TLS certificates to secrets/
# Generate RSA signing key: openssl genrsa 3072 > secrets/token_sign.pem
# Generate encryption key: openssl rand -base64 32 > secrets/encryption.key

Start the server:

docker compose up -d
docker compose logs -f

Using Docker Run:

mkdir -p data conf
cp .env.example conf/.env
# Edit conf/.env with your configuration

docker run -d \
  --name kiteworks-mcp \
  -p 8080:8080 \
  -e KW_MCP_ENV_FILE=/conf/.env \
  -v $(pwd)/data:/data \
  -v $(pwd)/conf:/conf:ro \
  kiteworks-mcp:latest

Complete Docker guide: dist/docker/DOCKER_DEPLOYMENT.md

Option 2: Systemd Service (Linux)

Install the binary and configure systemd service for process management:

# Install binary and configuration
sudo mkdir -p /opt/kiteworks-mcp
sudo cp kiteworks-mcp /opt/kiteworks-mcp/
sudo cp .env.example /opt/kiteworks-mcp/.env
# Edit /opt/kiteworks-mcp/.env with your configuration

# Install systemd service
sudo cp kiteworks-mcp.service /etc/systemd/system/

# Create service user
sudo useradd -r -s /bin/false mcp
sudo chown -R mcp:mcp /opt/kiteworks-mcp

# Enable and start
sudo systemctl enable kiteworks-mcp
sudo systemctl start kiteworks-mcp
sudo systemctl status kiteworks-mcp

Complete systemd guide: dist/systemd/SYSTEMD_SERVICE.md

Configuration

Configuration is managed through a .env file. See .env.example for all available options and docs/ENV_FILE_CONFIGURATION.md for detailed documentation.

Important: Set file permissions to 0600 for the .env file.

Building from Source and STDIO mode

If you're building the MCP server from source instead of using official builds, you'll need to complete a one-time OAuth login.

Prerequisites

Kiteworks OAuth Application

Create a custom OAuth application in your Kiteworks Admin Console following the same process as described in the Remote HTTPS Mode Prerequisites section, but use the redirect URI: http://localhost:9999/callback

Required Scopes:

  • Files: CREATE, READ, UPDATE, DELETE
  • Folders: CREATE, READ, UPDATE, DELETE
  • Search: READ
  • Users: READ

Save the Client Application ID and Client Secret Key securely.

Note: Linux requires GNOME Keyring (Secret Service dbus interface) for credential storage.

Build and Login

# Build
go build -o kiteworks-mcp ./cmd/kiteworks-mcp

# Run login (one-time OAuth authentication)
# Windows
kiteworks-mcp.exe login https://your.kiteworks.domain

# macOS / Linux
./kiteworks-mcp login https://your.kiteworks.domain

During login, you'll be prompted to enter your OAuth Client ID and Client Secret. Your browser will open automatically for Kiteworks authentication.

After login completes, configure your MCP client as shown in the Local STDIO Mode section.

Command Reference

The Kiteworks MCP Server provides the following commands:

Local STDIO Mode Commands

login

Login to Kiteworks via OAuth and store credentials (one-time authentication). Only required when building from source.

kiteworks-mcp login [flags] <kiteworks URL>

Flags:

  • --port, -p <port>: OAuth callback server port (default: 9999, range: 1024-65535)
  • --ca-cert, -c <path>: Path to custom CA certificate in PEM format

Example:

kiteworks-mcp login https://your.kiteworks.domain
kiteworks-mcp login --port 8080 --ca-cert /path/to/ca_chain.pem https://your.kiteworks.domain

start

Run the MCP Server in local STDIO mode.

kiteworks-mcp start [flags] <Kiteworks URL>

Flags:

  • --port, -p <port>: OAuth callback server port for token refresh (default: 9999)
  • --ca-cert, -c <path>: Path to custom CA certificate in PEM format
  • --insecure-absolute-paths: Allow absolute file paths (not recommended)
  • --enable-destructive-tools: Enable move and delete tools for files and folders (disabled by default)

Example:

kiteworks-mcp start https://your.kiteworks.domain
kiteworks-mcp start --ca-cert /path/to/ca_chain.pem https://your.kiteworks.domain
kiteworks-mcp start --insecure-absolute-paths https://your.kiteworks.domain

remove

Delete stored credentials and tokens.

kiteworks-mcp remove <Kiteworks URL>

test

Test connection and print current user information.

kiteworks-mcp test [flags] <Kiteworks URL>

Flags:

  • --ca-cert, -c <path>: Path to custom CA certificate in PEM format

Remote HTTPS Mode Commands

serve

Run the MCP Server in remote HTTPS mode for multi-user deployments. Configuration is loaded from environment variables or a .env file.

Note: This command requires configuration via environment variables. See docs/DEPLOYMENT_GUIDE.md, docs/ENV_FILE_CONFIGURATION.md, and .env.example for details.

General Commands

version

Print version information.

Usage Examples

Example 1: Quarterly Report Archive

What you say to Claude: "Create a Q1-2026 folder under Archives, find all files named 'Q1' across Kiteworks, move them there, and give me a summary"

What happens:

  1. search_folders finds the Archives folder → create_folder creates Q1-2026 inside it
  2. search_files finds all files matching "Q1" across your Kiteworks instance
  3. move_file moves all matched files into the new Q1-2026 folder in a single batch
  4. Claude summarizes: "Created Archives/Q1-2026 and moved 8 files (3 reports, 2 spreadsheets, 3 presentations)"

Example 2: Draft Cleanup

What you say to Claude: "Find all files with 'draft' in the name, show me what you find, and delete the ones older than 6 months"

What happens:

  1. search_files finds all files matching "draft"
  2. get_file_metadata retrieves dates for each file; Claude filters to those older than 6 months
  3. Claude presents the list and asks for confirmation
  4. delete_file soft-deletes the confirmed files in batch
  5. Claude summarizes: "Found 14 draft files. Deleted 9 files older than 6 months (recoverable until retention expires). 5 recent drafts kept."

Example 3: Sensitive Data Audit

What you say to Claude: "Search for any files named 'passwords', 'credentials', or 'secrets' and tell me where they are stored"

What happens:

  1. search_files runs three searches across your Kiteworks instance
  2. get_file_metadata retrieves owner, location, and sharing status for each match
  3. Claude produces an audit report: "Found 3 potentially sensitive files: passwords.xlsx in Shared/IT (owner: admin, shared), credentials.txt in My Folder (owner: you, private), secrets.env in DevOps/Config (owner: devops-lead, shared with 4 users). Recommend moving these to a restricted folder or deleting them."

Example 4: Compliance Review with Forms

What you say to Claude: "Create a vendor compliance checklist form with sections for data handling, security certifications, and incident response procedures"

What happens:

  1. get_create_form_schema retrieves the form schema so Claude understands the format
  2. Claude builds a structured form with dropdown, checkbox, and text fields across three sections
  3. Claude generates an HTML preview for your review
  4. After approval, create_form uploads the form to Kiteworks and returns the editor link
  5. Claude responds: "Vendor compliance form created with 15 fields across 3 sections. Preview and edit at: https://your.kiteworks.domain/advancedform/..."

Example 5: Project Handover

What you say to Claude: "Reorganize the Alpha Project folder: create subfolders for Contracts, Deliverables, and Correspondence, then sort all files into the right subfolder based on their names"

What happens:

  1. search_folders locates the Alpha Project folder
  2. create_folder creates three subfolders (Contracts, Deliverables, Correspondence)
  3. get_folder_children lists all files in the Alpha Project root
  4. get_file_metadata inspects each file; Claude classifies by name patterns (e.g., "SOW-" → Contracts, "-deliverable-" → Deliverables, "email-" → Correspondence)
  5. move_file moves each group of files into the appropriate subfolder
  6. Claude summarizes: "Organized 23 files into 3 subfolders: Contracts (7), Deliverables (11), Correspondence (5)"

Example 6: Collect and Download Deliverables for Review

What you say to Claude: "Find all files with 'deliverable' in the name from the last 30 days, download them to my ./review folder, and create a summary document listing each file with its size and date"

What happens:

  1. search_files finds all files matching "deliverable"
  2. get_file_metadata retrieves size and dates; Claude filters to the last 30 days
  3. download_file_to_path downloads each file to ./review/
  4. Claude generates a Markdown summary table and upload_file_from_path uploads it as review-summary.md to the same Kiteworks folder
  5. Claude responds: "Downloaded 6 deliverables (47 MB total) to ./review/ and uploaded review-summary.md with the index"

Available Tools

The MCP Server exposes the following tools to AI assistants:

File Operations — Path-Based (STDIO Mode Only)

  • download_file_to_path: Download a file from Kiteworks to local filesystem by file ID
  • upload_file_from_path: Upload a file from local filesystem to a Kiteworks folder

File Operations — Content-Based (All Modes)

  • read_file_contents: Read file contents into conversation context as base64 (not for local download)
  • create_file_from_content: Create a file in Kiteworks from base64 content in conversation context (not for local upload)

File Operations — Metadata (All Modes)

  • get_file_metadata: Retrieve file metadata by ID
  • rename_file: Rename a file by ID
  • move_file: Move one or more files to a different folder
  • delete_file: Delete one or more files (with confirmation)

Folder Operations

  • get_top_folders: Fetch top-level folders with optional filtering
  • get_folder_children: Fetch folder contents by parent ID with filtering
  • create_folder: Create a new folder with specified options
  • rename_folder: Rename a folder by ID
  • move_folder: Move a folder to a different parent folder
  • delete_folder: Delete one or more folders and their contents (with confirmation)

Search Operations

  • search: Search folders and/or files by name
  • search_folders: Search folders only by name
  • search_files: Search files only by name or content

Forms

  • create_form: Generate Kiteworks Secure Data Forms from templates with preview links
  • get_create_form_schema: Retrieve the JSON schema for form creation

User Operations

  • get_user_info_whoami: Get current Kiteworks user information

Resources

  • users://me: Current user information
  • forms://schema: JSON schema for form creation

Security Features

FIPS 140-3 Compliance

The server supports FIPS 140-3 mode when run with GODEBUG=fips140=only. In this mode:

  • Encryption: AES-256-GCM with FIPS-compliant random nonce generation
  • TLS: Minimum TLS 1.3 with NIST-approved curves (P-256); non-FIPS curves (X25519) are automatically disabled
  • Hashing: SHA-256 for credential file naming and integrity checks

FIPS 140-3 status is logged at server startup.

Quantum-resistant forward secrecy (FIPS 203)

  • Post-Quantum: Hybrid X25519+ML-KEM-768 key exchange for quantum-resistant forward secrecy (FIPS 203)

TLS Certificate Verification

If your Kiteworks instance uses a self-signed certificate, supply the Root CA chain using the --ca-cert flag:

kiteworks-mcp login --ca-cert ca_cert_chain.pem https://your.kiteworks.domain
kiteworks-mcp start --ca-cert ca_cert_chain.pem https://your.kiteworks.domain

Note: The CA certificate must be in PEM format and contain the complete certificate chain.

Path Security

By default, for additional security, the MCP Server restricts file operations to relative paths only. Uploads and Downloads will use the current working directory of the MCP Client. You can enable full file system access using the --insecure-absolute-paths flag of the "start" command.

When enabled, file operations can access:

  • Full system directories: /home/user/documents/file.txt
  • Root filesystem access: /etc/passwd, /var/log/system.log
  • Windows system paths: C:\Windows\System32\config.txt

Relative path examples (default):

upload_file(parent_id="folder123", source="./report.pdf")
download_file(file_id="file456", target="./downloads/file.xlsx")

Absolute path examples (requires flag):

upload_file(parent_id="folder123", source="/Users/john/Desktop/report.pdf")
download_file(file_id="file456", target="C:\Users\jane\Documents\file.xlsx")

Privacy Policy

This MCP Server collects and stores user consent about the LLM accessing data and metadata stored in Kiteworks. No other data is collected by the MCP Server. For complete Kiteworks privacy information, see our privacy policy: https://www.kiteworks.com/privacy-policy

Data Collection

  • User consent
  • Proof of acknowledgement, stored encrypted locally
  • Not shared with third parties
  • Retained until the Kiteworks connection is deleted

Additional Resources