TweekIT MCP Server

TweekIT MCP Server & Python SDK

Ingest, Preflight, and Convert Just About Any Filetype Into AI Workflows — Official Open-Source Package by AMPS dba Equilibrium

Current version: v1.8.0

🤖 Claude & AI Hub Users: Tired of "unsupported file type" errors? Jump to our Claude File Format Enabler – a browser-based tool that converts 450+ formats (DOC, XLS, PSD, DWG, Camera RAW, etc.) into AI-compatible files in seconds, or use our built-in Python preflight_check and TweekitClient SDK directly in your pipeline.

Overview

TweekIT MCP Server is the universal media translator for AI workflows, making any file ready for processing in seconds. Built on the robust content processing engine of Equilibrium's MediaRich Server, a technology developed since 2000 and trusted by massive portals and media companies worldwide, TweekIT brings decades of expertise in handling complex media, drawing on a pedigree that includes the renowned DeBabelizer.

With TweekIT, you can upload, preview, transform, and download over 400 supported file types using a consistent API or widget interface. It removes the pain of unpredictable input formats by automatically normalizing and preparing assets for the next step in your workflow.

What is TweekIT?

TweekIT is a universal media ingestion and transformation service designed to take any supported file and make it AI ready in seconds. Whether you are normalizing formats, resizing assets, or extracting a single page from a complex document, TweekIT provides a consistent, API first way to get exactly the output you need without worrying about the quirks of individual file types.

Why use it in an MCP context?

In a Model Context Protocol (MCP) workflow, TweekIT acts like a universal translator for media. It sits between your AI agent and the unpredictable real world files it encounters, ensuring every asset is transformed into a compatible, standardized format before processing. This is similar to how GitHub Actions streamlines software automation, but applied to media handling in AI pipelines.

With TweekIT in your MCP toolset, your agents can:

• Accept a wider range of inputs from users without failure
• Automatically apply transformations such as cropping, resizing, format conversion, and background changes
• Pass clean, ready to use assets to the next step in your AI workflow with no manual intervention fixing the constant customer file ingestion failures we are all to familiar with

🤖 Claude Users: See Solving Claude's File Type Limitations for a dedicated guide on using TweekIT to overcome Claude's built-in file format restrictions and our standalone web converter tool.

Example scenario

A user uploads a scanned PDF of an ID card as part of an onboarding process. Your MCP agent calls TweekIT to:

• Convert the PDF to a PNG image
• Crop to just the ID card
• Resize to a standard 300x300 pixel headshot
• Return the transformed image directly into the verification pipeline

The entire process happens in seconds, and your workflow never sees an incompatible file format.

Key Capabilities

• Supports 400+ file types for seamless ingestion and conversion, leveraging a core engine refined over two decades to handle dynamic imaging and video processing.
• Stateless and API first design for fast, scalable integrations
• Widget or REST API access to fit any application architecture
• Enterprise grade security with secure key handling and short lived asset storage
• Instant compatibility fixes that prevent AI pipeline failures from bad input formats immediately

Try it now

• AI File Format Enabler – Browser-based converter for Claude, OpenAI, and other AI tools (DOC, XLS, PSD, DWG → PDF/PNG)
• Live Demo – Upload and transform files in your browser
• Use Case Examples – See practical workflows and code samples on the website. The specific MCP manifest conversions are shown in section 7 below.

Table of Contents

• Overview
• Solving Claude's File Type Limitations
• Requirements
• Installation
• Quickstart
• Authentication
• Server and Hosting
• Client Compatibility
  • Quickstart (Claude Desktop)
  • Quickstart (ChatGPT MCP)
  • Quickstart (Cursor IDE)
  • Quickstart (Continue IDE)
  • Quickstart (OpenAI Codex CLI)
• Rate Limits and Pricing
• Core Concepts
• MCP API Reference
• REST API Reference
• Use Cases
• Demo + Show Code
• Error Handling and Troubleshooting
• Advanced Topics
• Registry Readiness
• Resources

Requirements

• Python 3.10 or later
• Docker (optional, for containerized builds)
• httpx library for HTTP requests
• FastMCP for tool registration and server functionality

Installation

Option 1: Install from PyPI (recommended)

# Using pippip install tweekit
# Using uvuv pip install tweekit
# Run directly as an MCP server with zero local setup via uvxuvx tweekit --transport stdio
# Using pipx / uv tool (isolated CLI environment)uv tool install tweekit

Run the MCP server locally (tweekit and tweekit-mcp CLIs are both installed):

tweekit-mcp --transport streamable-http --port 8080

The CLI wraps server.py and accepts the same flags (--transport, --host, --port).

Python SDK Quickstart (tweekit / tweekit_mcp)

Installing tweekit from PyPI ships the full Python SDK (import tweekit or import tweekit_mcp) for both MCP client workflows and direct REST API integrations, plus the AI Hub preflight & modality router (powering Maitrix AI Hub multimodal file ingestion):

import asynciofrom pathlib import Pathfrom tweekit import (    TweekitClient,    TweekitDirectClient,    preflight_check,)
# 1. Instant local preflight & AI provider format recommendation (no network roundtrip)check = preflight_check("blueprint.dwg", target_provider="claude")print(check["supported"], check["category"], check["recommended_outfmt"])# -> True, 'design_vector_cad', 'png'
# 2. Direct Async Python SDK (calls TweekIT API directly via httpx)async def run_direct():    async with TweekitDirectClient() as api:        result = await api.convert_file(            Path("presentation.ppt"),            outfmt="pdf",            output_path=Path("presentation_ai_ready.pdf"),        )        print("Saved:", result)
# 3. Async MCP Client (connects to https://mcp.tweekit.io/mcp or local stdio server)async def run_mcp():    async with TweekitClient() as client:        tools = await client.list_tools()        batch_results = await client.batch_convert([            {"url": "https://example.com/scan.tiff", "outfmt": "png"},            {"path": "legacy_sheet.xls", "outfmt": "pdf"},        ])        print("Tools:", tools, "Batch:", len(batch_results))
asyncio.run(run_direct())

Option 2: Clone the repository

git clone https://github.com/equilibrium-team/tweekit-mcp.gitcd tweekit-mcpuv sync            # or: pip install -r requirements.txt

Set environment variables as needed:

• PORT – Streamable HTTP port (default: 8080).
• PLUGIN_PROXY_PORT – Port for the ChatGPT plugin proxy (default: 8080 when running standalone).
• MCP_SERVER_PORT – Internal port for the MCP server when using start_services.sh (default: 8000).

Quickstart

Step 1: Sign Up

Create your free TweekIT account and get started with 10,000 API calls included at no cost.
Pricing and Signup here to generate your API credentials in the MANAGE ACCOUNT page and start using the service.

Step 2: Choose Your Authentication Method

TweekIT supports multiple authentication methods. However ONLY the Key/Secret pair method will work with the MCP integration.

• API Key and Secret – Required for MCP production use, more secure and easier to control access

You will find these values in your account dashboard after sign up. Keep them safe and never expose them in client-side code.

Step 3: Make Your First API Call

Below is a minimal working json example that sends an image with a basic resize operation, previews the transformation, and returns the result. This example uses API Key and Secret authentication.

The JSON was captured from the use of MCP Inspector with the publicly available MCP server.

{  "method": "tools/call",  "params": {    "name": "convert",    "arguments": {      "apiKey": "{Your TweekIT API key}",      "apiSecret": "{Your TweekIT API secret}",      "inext": "png",      "outfmt": "png",      "blob": "iVBORw0KGgoAAAANSUhEUgAAABwAAAA6CAYAAACj+Dm/AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAAsSAAALEgHS3X78AAAAHnRFWHRTb2Z0d2FyZQBFcXVpbGlicml1bSBNZWRpYVJpY2h7w4AAAAAB30lEQVRYhe2Xv0vDQBTHP4rQTRGhLqKiYt38MaggKIi46e6im2Rw7FJw7NAh4uAi+h/oIDgKnR3VQZROKiLYrZtOOiQH1+RevJQ0INwXQt7de7lP++7l7tJTq9XIU7250hzQAR3QAR3QAXMH3gM/wG0ewHtgNrSXgXo3gXUNprTSLaAPrBv6C4DXDeBBgm8ha+ArwT+RNJkl8BoY/SNmKiugB2xaxA1nBayQnEolY+GkBdqkUlescNIAPWBL8D0I/bHCSQOsCP3fwFx4jypWOLbApFRehfdPgy9WODbApKpsATuh/WHwxwrHBphUlRea/SLErKUBniGn8g3Y19qPQtx4GuBugu8y0q4KcRN6oy9hwFvkVDaAfoKtaQgYBAaE2KINsE6wkUqaDi9b+UBZAn5ht3Sl0bwyTHOYNQxgRAIad+kMNJY3sAAcQvscesQPQ7qaBPP7Bbxr/XeaXab9BKdrMQrcS4AdhYPZ6EkArkJ7SucNQRC8c7YwCNZW084xAPgKeI25Or+B4xQwpWehf0MBl4SAG+C0A6D0zIwCFg3OJrDdAUwBTaeAggI2DM6TDmFKcwT7pa6GApY0aAs4R17908gnyBTh+CX9tShlAIiqSuSH/+sPUgd0QAf8J8BfT2hGnMaA5CUAAAAASUVORK5CYII=",      "noRasterize": false,      "width": 30,      "height": 30,      "page": 1,      "bgcolor": ""    }  },  "jsonrpc": "2.0",  "id": 4}

Step 4: See It in Action

You can explore TweekIT visually before writing any code. The live demo lets you upload files, apply transformations, and download the results instantly.

• Open the Live Demo
• View Use Case Examples for real workflows and code samples

Authentication

TweekIT supports multiple authentication methods (REST API, APP ID method is ONLY for using). Set up your API Key and Secret so you can start quickly while maintaining security best practices.

For MCP Server Use: API Key + Secret

This is the most secure and flexible option. Use this for all production deployments.

Steps:

1. Generate your API Key and Secret in your TweekIT account settings.
2. Store them securely — never commit to source control.
3. Use server-side code or a reverse proxy to inject credentials into requests.

Security Tips:

• Always use a reverse proxy or other server-side method to protect credentials.
• Never embed secrets in client-side code.

Next Steps:
Once authenticated, you can:

• Upload media as part of the request using Base-64
• Recieve output

Server and Hosting

Hosted ready MCP server

All tools and resources are available here, used for testing and free trials:

• Public MCP endpoint (HTTP transport): https://mcp.tweekit.io/mcp

The currently available resource name is 'version'. The currently available tool names are 'doctype', 'convert', and 'convert_url'. See below for parameters, or query the MCP server as it will return metadata instructing use of each of these.

Versioning & Build Numbers

The project tracks semantic versions in major.minor.build format (for example, 1.8.0). Use scripts/bump_version.py to keep every metadata file aligned:

# Increment just the build number (e.g., 1.8.0 -> 1.8.1)python scripts/bump_version.py --bump-build
# Set an explicit versionpython scripts/bump_version.py --set 1.8.0

The script updates VERSION, pyproject.toml, server.py, server.json, claude/manifest.json, README.md, and uv.lock so container builds, manifests, and docs stay synchronized.

MCP Installation

You can run the TweekIT MCP server locally or connect to a hosted instance. The local option is recommended for development and testing.

Local Installation

git clone https://github.com/equilibrium-team/tweekit-mcp.gitcd tweekit-mcppip install -r requirements.txt

Run the server:

uv run server.py

The server will listen on:

• http://localhost:8080

Config Options

Local Development Mode
By default, server.py will bind to localhost on port 8080. You can override the port with the PORT environment variable:

PORT=9090 uv run server.py

Cloud Run Deployments

Use the provided script to build and deploy containerized stage or production services on Google Cloud Run.

Prerequisites:

• Google Cloud project access (tweekitmcp-a26b6 by default).
• gcloud CLI authenticated (gcloud auth login) and, if your standard config directory is read-only, a writable export such as export CLOUDSDK_CONFIG="$(pwd)/.gcloud-config".

Run the container locally with Docker (builds image tweekit-mcp-local:dev and binds to 8080):

bash scripts/deploy_cloud_run.sh local --version dev

Deploy to staging (creates/updates the tweekit-mcp-stage service):

bash scripts/deploy_cloud_run.sh stage --version 1.8.0

Deploy to production (updates the tweekit-mcp service):

bash scripts/deploy_cloud_run.sh prod --version 1.8.0

Pass --project <PROJECT_ID> if you need to override the active gcloud configuration, and --env-file <path> to supply Cloud Run environment variables in YAML format.

The helper scripts never bundle credentials. Always provide your own Google Cloud project, region, and secret sources when running them; Equilibrium’s staging/prod keys live in managed secret stores and are intentionally excluded from this repository.

Python dependencies for Firebase Functions are resolved at deploy time. scripts/deploy_firebase.sh will vendor them into functions/packages/ locally (a gitignored directory) so the repo stays lightweight.

Client Compatibility

• Claude Desktop / claude.ai: Compatible (HTTP transport; .mcpb bundle available).
• ChatGPT (OpenAI): Compatible (HTTP transport; plugin proxy available).
• OpenAI Codex CLI: Compatible (--mcp-server flag or ~/.codex/config.yaml).
• Cursor: Compatible (HTTP transport via ~/.cursor/mcp.json).
• Continue (VS Code / JetBrains): Compatible (Streamable HTTP via ~/.continue/config.json).
• Windsurf / Sourcegraph Cody: Compatible (HTTP MCP endpoints via beta settings).

Examples

• Claude Desktop (config snippet):

  json

  {  "mcpServers": {    "tweekit": {      "transport": { "type": "http", "url": "https://mcp.tweekit.io/mcp" }    }  }}

• Claude tool call (arguments example):

  json

  {  "name": "convert",  "arguments": {    "apiKey": "YOUR_KEY",    "apiSecret": "YOUR_SECRET",    "inext": "png",    "outfmt": "webp",    "blob": "<base64>",    "width": 300,    "height": 300  }}

• OpenAI (Node, using MCP TypeScript client):

  ts

  import { Client } from "@modelcontextprotocol/sdk/client";import { HttpClientTransport } from "@modelcontextprotocol/sdk/client/transport/http";
  const transport = new HttpClientTransport(new URL("https://mcp.tweekit.io/mcp"));const client = new Client({ name: "tweekit-example", version: "1.0.0" }, { capabilities: {} }, transport);await client.connect();const tools = await client.listTools();const res = await client.callTool({  name: "doctype",  arguments: { ext: "pdf", apiKey: process.env.TWEEKIT_API_KEY, apiSecret: process.env.TWEEKIT_API_SECRET },});console.log(res);

• OpenAI (Python, quick call):

  py

  import asyncioimport os
  from fastmcp import Client
  async def main():    async with Client("https://mcp.tweekit.io/mcp") as c:        print(await c.list_tools())        out = await c.call_tool(            "convert",            {                "apiKey": os.environ["TWEEKIT_API_KEY"],                "apiSecret": os.environ["TWEEKIT_API_SECRET"],                "inext": "png",                "outfmt": "txt",                "blob": "<base64>",            },        )        print(out)asyncio.run(main())

Quickstart (Claude Desktop)

There are two ways to use Tweekit inside Claude Desktop:

1. Hosted HTTP server – point Claude at https://mcp.tweekit.io/mcp via Settings → Connectors → Advanced → Developer Mode → “Add HTTP server.”
2. Local bundle (.mcpb) – install the packaged stdio server so you can work offline or ship curated builds.

We maintain the local bundle with scripts/build_claude_bundle.py and the guided helper scripts/configure_claude_desktop.py. The helper walks through version selection, bundle generation, dxt manifest validation, and finally reminds you to import the resulting dist/tweekit-claude.mcpb. It also reiterates that our production Tier 1 headless nodes run on Equilibrium-owned CPUcoin enterprise miners inside SAS 70 / ISO 27001 compliant data centers—the local bundle mirrors the same feature set.

After connecting (either method):

• Ask: “List supported input types via doctype.”
• Or call convert with your key/secret and a base64 blob:

{  "name": "convert",  "arguments": { "apiKey": "…", "apiSecret": "…", "inext": "png", "outfmt": "webp", "blob": "<base64>" }}

Quickstart (ChatGPT MCP)

If your ChatGPT environment supports MCP tools, add an HTTP MCP server pointing to the public endpoint.

1. Configure server: URL https://mcp.tweekit.io/mcp (HTTP transport)
2. Use tools in a chat:

• doctype

{ "name": "doctype", "arguments": { "ext": "pdf", "apiKey": "…", "apiSecret": "…" } }

• convert

{  "name": "convert",  "arguments": {    "apiKey": "…",    "apiSecret": "…",    "inext": "png",    "outfmt": "txt",    "blob": "<base64>"  }}

Quickstart (Cursor IDE)

Cursor loads MCP configuration from ~/.cursor/mcp.json. To enable the hosted TweekIT server, merge the snippet below (also published at configs/cursor-mcp.json) into your existing file:

{  "mcpServers": {    "tweekit": {      "type": "http",      "url": "https://mcp.tweekit.io/mcp",      "headers": {        "ApiKey": "${TWEEKIT_API_KEY}",        "ApiSecret": "${TWEEKIT_API_SECRET}"      }    }  }}

• Copy .env.example to .env, fill in TWEEKIT_API_KEY / TWEEKIT_API_SECRET, then source .env (or export the variables manually).

2. Restart Cursor and run “List tools” to confirm version, doctype, convert, and convert_url are available.
3. Optional: host the JSON internally and surface an “Add to Cursor” deep-link for teammates.

Quickstart (Continue IDE)

Continue (VS Code / JetBrains) stores MCP servers in ~/.continue/config.json. Add the TweekIT server under mcpServers (ready-to-copy JSON at configs/continue-mcp.json):

{  "mcpServers": {    "tweekit": {      "type": "streamable-http",      "url": "https://mcp.tweekit.io/mcp",      "headers": {        "ApiKey": "${TWEEKIT_API_KEY}",        "ApiSecret": "${TWEEKIT_API_SECRET}"      }    }  }}

After saving the configuration:

1. Reload Continue so it picks up the new MCP entry.
2. Use the Continue “Tools” panel to call doctype, convert, or convert_url with the appropriate parameters.
3. Document workspace-specific credential steps so teammates can connect quickly.

Quickstart (OpenAI Codex CLI)

OpenAI Codex CLI (@openai/codex) supports MCP servers as first-class plugins. There are two ways to add TweekIT:

Option A — One-liner easy plugin (no config file needed):

export TWEEKIT_API_KEY=your_key TWEEKIT_API_SECRET=your_secretcodex --mcp-server tweekit:https://mcp.tweekit.io/mcp

Pass the --mcp-server flag each session, or alias it in your shell profile for permanent access.

Option B — Persistent config (~/.codex/config.yaml):

Merge the entry below (also at configs/codex-mcp.yaml) into your Codex config:

mcpServers:  tweekit:    type: http    url: https://mcp.tweekit.io/mcp    headers:      ApiKey: “${TWEEKIT_API_KEY}”      ApiSecret: “${TWEEKIT_API_SECRET}”

After connecting via either method:

• Ask: “List supported input types via TweekIT doctype.”
• Or: “Use TweekIT to convert this DOC file to PDF so you can read it.”
• Or: “Convert the image at <url> to WebP at 800×600.”

Install Codex CLI: npm install -g @openai/codex

Rate Limits and Pricing

TweekIT offers a generous free tier so you can explore and integrate without cost.

Free Tier

• 10,000 API calls included at no charge.
• Full access to all core upload, preview, download, and delete capabilities.
• No credit card required to start.

Paid Plans

If you exceed the free tier limit, you can upgrade to a paid plan at any time.
See the full pricing guide for details. You must have a token key pair to use the MCP Server:
https://www.tweekit.io/pricing/

Handling Rate Limit Errors

When you reach your monthly quota, the API will respond with an HTTP 429 Too Many Requests status.

MCP Integration Tip:
Your MCP client should:

1. Catch 429 responses.
2. Surface a clear error message to the user.
3. Recommend upgrading the plan immediately to continue.

Core Concepts

Understanding these core concepts will help you get the most out of TweekIT in an MCP workflow.

Request includes Base-64 content → Response include Base-64 Results

TweekIT MCP Server uses this simple, stateless and secure pipeline for document processing requests.

Transformations

TweekIT supports a wide range of transformations, applied at preview time:

• Resize by width and height (if send only one parameter, the other will be automatically calculated to maintain aspect ratio)
• OutFormat change the file format to a different file type
• Background color fills for transparent or padded areas
• NoRasterize When combined with a PDF output format, converts entire textual documents into a PDF file for upstream AI ingest.

Stateless Processing

TweekIT does not store your files persistently.

• Job folder and temp storage are purged after each request.
• This design ensures minimal storage overhead and stronger privacy for sensitive files.
• Data in transit is encrypted via SSL.

MCP Reference

Resources

/version

Description: Fetches the current version of the TweekIT API. Takes no parameters.

/server-version

Description: Returns this MCP server's version string (e.g., 1.8.0). Takes no parameters.

Tools

/doctype

Description: Retrieves a list of supported input file formats or maps a file extension to its document type. If the document type field returned is empty, then the format isn't supported for reading.

Parameters:

• extension: File extension (e.g., jpg, docx). Optional, defaults to '*'. (return all supported input document types).
• apiKey: API key for authentication.
• apiSecret: API secret for authentication.

/convert

Description: Converts a base64-encoded document to the specified output format.

Parameters:

• apiKey: API key for authentication.
• apiSecret: API secret for authentication.
• inext: Input file extension (e.g., jpg, png, doc, docx, etc.).
• outfmt: Desired output format (e.g., jpg, pdf, png).
• blob: Base64-encoded document data.

Optional:

• noRasterize: If the input document is a text-based document (doc, odt, xls, etc.) and the output format is set to 'pdf' with this parameter set to true, instead of rasterizing and doing image operations on the document, all pages will be converted to a PDF and returned. If the output format is not 'pdf', this parameter is ignored. Defaults to false.
• width: Desired width of the output (default: 0 for no resizing).
• height: Desired height of the output (default: 0 for no resizing).
• x1, y1, x2, y2: Integee crop coordinates. Defaults to all 0 (no cropping). Cropping is applied before the resize. The x1 and y1 values can be negative, which adds padding to the top and left; the x2 amd y2 can be greater than the original raster size, which adds padding to the right and bottom.
• page: Page number to convert (for multi-page documents, default: 1).
• alpha: boolean (defaults to True - pass alpha channel through if output format supports it) If false, then the alpha channel is removed and the pixels are replaced with the bgColor value.
• bgColor: Background color padding or when transparent documents need to have their alpha channel removed. (default: "000000" or black). Is is okay to precede the hex value with a '#' (web color indicator)

The image of the specified page (or page 1) will be returned in the response with the correct content type set. If noRasterize is set to true and all other conditions are met, a PDF of the contents of the entire submitted document will be returned.

/convert_url

Description: Downloads a remote document over HTTP(S) and routes it through the TweekIT conversion pipeline without requiring the caller to supply base64 input.

Parameters:

• apiKey: API key for authentication.
• apiSecret: API secret for authentication.
• url: HTTPS or HTTP URL pointing to the source document.
• outfmt: Desired output format (e.g., jpg, pdf, png).

Optional:

• inext: Override for the input extension. When omitted, the server deduces it from the URL path or the response content-type header.
• noRasterize, width, height, x1, y1, x2, y2, page, alpha, bgColor: Same semantics as /convert.
• fetchHeaders: Object of HTTP headers (e.g., Authorization) to include when downloading the remote asset.

Returns: Same as /convert—binary image/file payloads surface as FastMCP Image/File objects; JSON responses are passed through.

/search

Description: Performs a lightweight DuckDuckGo query (no API keys required) and returns { query, results: [{ title, url, snippet }] }. It’s designed to help you locate public documents or images, then feed the URL directly into /convert_url. If your environment needs a different provider, swap the HTTP call in server.py—docs/quickstarts.md explains the rationale and where to customize it.

Parameters:

• query: Search query string.
• max_results: Maximum number of results to return (default: 5, max: 10).

/fetch

Description: Fetches a URL and returns content based on content-type.

Parameters:

• url: The http or https URL to fetch.

Returns:

• Image content as image resource for image/* responses.
• PDF as resource with format="pdf" for application/pdf.
• Text/JSON as a JSON object with text and metadata.
• Other binary as a generic resource with format="bin".

REST API Reference

Please refer to the documentation at (https://tweekit.io/docs/rest-api/) to get an understanding of how the MCP server talks to the TweekIT REST API to proxy MCP requests to TweekIT.

Use Cases

Below are common workflows where TweekIT improves reliability and speed in media processing. Each example shows both REST API and MCP usage patterns.

1. Employee Headshot Automation

Automatically crop and resize images into a consistent size and format.

MCP Example

{  "method": "tools/call",  "params": {    "name": "convert",    "arguments": {      "apiKey": "{Your TweekIT API key}",      "apiSecret": "{Your TweekIT API secret}",      "inext": "png",      "outfmt": "png",      "blob": "iVBORw0KGgoAAAANSUhEUgAAABwAAAA6CAYAAACj+Dm/AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAAsSAAALEgHS3X78AAAAHnRFWHRTb2Z0d2FyZQBFcXVpbGlicml1bSBNZWRpYVJpY2h7w4AAAAAB30lEQVRYhe2Xv0vDQBTHP4rQTRGhLqKiYt38MaggKIi46e6im2Rw7FJw7NAh4uAi+h/oIDgKnR3VQZROKiLYrZtOOiQH1+RevJQ0INwXQt7de7lP++7l7tJTq9XIU7250hzQAR3QAR3QAXMH3gM/wG0ewHtgNrSXgXo3gXUNprTSLaAPrBv6C4DXDeBBgm8ha+ArwT+RNJkl8BoY/SNmKiugB2xaxA1nBayQnEolY+GkBdqkUlescNIAPWBL8D0I/bHCSQOsCP3fwFx4jypWOLbApFRehfdPgy9WODbApKpsATuh/WHwxwrHBphUlRea/SLErKUBniGn8g3Y19qPQtx4GuBugu8y0q4KcRN6oy9hwFvkVDaAfoKtaQgYBAaE2KINsE6wkUqaDi9b+UBZAn5ht3Sl0bwyTHOYNQxgRAIad+kMNJY3sAAcQvscesQPQ7qaBPP7Bbxr/XeaXab9BKdrMQrcS4AdhYPZ6EkArkJ7SucNQRC8c7YwCNZW084xAPgKeI25Or+B4xQwpWehf0MBl4SAG+C0A6D0zIwCFg3OJrDdAUwBTaeAggI2DM6TDmFKcwT7pa6GApY0aAs4R17908gnyBTh+CX9tShlAIiqSuSH/+sPUgd0QAf8J8BfT2hGnMaA5CUAAAAASUVORK5CYII=",      "noRasterize": false,      "width": 30,      "height": 30,      "page": 1,      "bgcolor": ""    }  }}

Equivalent REST Example (requires a separate upload step)

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}" \  -H "Content-Type: application/json;charset=UTF-8" \  -d '{"width": 30, "height": 30, "fmt": "png"}'

2. KYC Photo Ingestion and Normalization

Process identity document photos into standardized formats for automated verification.

MCP Example

{  "method": "tools/call",  "params": {    "name": "convert",    "arguments": {      "apiKey": "{Your TweekIT API key}",      "apiSecret": "{Your TweekIT API secret}",      "inext": "jpg",      "outfmt": "webp",      "blob": "{Your base64 encoded photo}",      "width": 600,      "height": 600,      "bgcolor": "FFFFFF"    }  }}

Equivalent REST Example

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}" \  -H "Content-Type: application/json;charset=UTF-8" \  -d '{"width": 600, "height": 400, "fmt": "webp", "bgcolor": "#FFFFFF"}'

3. Social Media and E-Commerce Image Resizing

Generate platform-specific product images with correct aspect ratios and background fills.

MCP Example

{  "method": "tools/call",  "params": {    "name": "convert",    "arguments": {      "apiKey": "{Your TweekIT API key}",      "apiSecret": "{Your TweekIT API secret}",      "inext": "jpg",      "outfmt": "jpg",      "blob": "{Your base64 encoded photo}",      "width": 1080,      "height": 1080,      "bgcolor": "FFFFFF"    }  }}

Equivalent REST Example

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}" \  -H "Content-Type: application/json;charset=UTF-8" \  -d '{"width": 1080, "height": 1080, "fmt": "jpg", "bgcolor": "#FFFFFF"}'

4. Cross-Platform Asset Conversion

Convert files between formats for compatibility across different tools and workflows.

MCP Example

{  "method": "tools/call",  "params": {    "name": "convert",    "arguments": {      "apiKey": "{Your TweekIT API key}",      "apiSecret": "{Your TweekIT API secret}",      "inext": "{filename extension of the input doc}",      "outfmt": "webp",      "blob": "{Your base64 encoded document}"    }  }}

Equivalent REST Example

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}" \  -H "Content-Type: application/json;charset=UTF-8" \  -d '{"fmt": "webp"}'

5. Multi-page Document conversion to PDF

Convert complex document or legacy filetypes from original formats into PDF files for compatibility into your current AI workflow.

MCP Example

{  "method": "tools/call",  "params": {    "name": "convert",    "arguments": {      "apiKey": "{Your TweekIT API key}",      "apiSecret": "{Your TweekIT API secret}",      "inext": "{filename extension of the input doc}",      "outfmt": "pdf",      "noRasterize": true,      "blob": "{Your base64 encoded document}"    }  }}

Equivalent REST Example

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}" \  -H "Content-Type: application/json;charset=UTF-8" \  -d '{"fmt": "pdf", noRasterize: true}'

Explicit Document Cleanup (REST API)

To immediately delete a document and all its associated files before the 20-minute auto-expiry, use the DELETE endpoint. This is useful when a user cancels a workflow mid-session. The MCP delete_document tool wraps this call.

curl -X DELETE "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}"

Note: Documents expire automatically after 20 minutes regardless. Explicit deletion is optional but recommended for security-sensitive workflows.

Demo + Show Code

TweekIT includes an interactive MCP-ready demo that lets you try the upload, preview, and transformation workflow in your browser — then see the exact code needed to reproduce those actions in your own project.

Interactive Tweekit Demo

Open the Live Demo to:

1. Upload any supported file.
2. Preview transformations such as resize, crop, background fill, and format conversion.
3. Download the transformed output.

Upload Preview UI

The demo provides a drag-and-drop or click-to-upload interface for selecting files. Once uploaded, you’ll see:

• File name and type.
• Generated DocId (expires in 20 minutes).
• Original image preview.

Transformation UI

Adjust transformation parameters directly in the browser:

• Resize dimensions.
• Crop area (rectangular or elliptical).
• Output format.
• Background color fill.

Changes are applied in real time using the same REST endpoints your application will call.

Auto-Generate Code Tabs

Every action in the demo can display corresponding code for:

• Node.js

  javascript

  await fetch(`https://www.tweekit.io/tweekit/api/image/preview/${docId}`, {  method: 'POST',  headers: { "apikey": "{Your API Key}", "apisecret": "{Your API Secret}" },  body: JSON.stringify({ width: 300, height: 300, fmt: 'png' })});

• curl

  bash

  curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \  -H "apikey: {Your API Key}" \  -H "apisecret: {Your API Secret}" \  -H "Content-Type: application/json;charset=UTF-8" \  -d '{"width": 300, "height": 300, "fmt": "png"}'

Error Handling and Troubleshooting

Building robust MCP workflows with TweekIT means anticipating and handling common error scenarios. The API returns clear HTTP status codes and error payloads so your client or MCP action can respond appropriately.

Common Issues

Bad Format

• Cause: The file format is unsupported or the requested output format is invalid.

• Resolution: Check the supported file formats list in the docs. Ensure transformations request a valid fmt value.

• HTTP Status: 400 Bad Request

• Error Example:

  json

  {  "error": "invalid_format",  "message": "The requested format is not supported."}

Quota Exceeded

• Cause: Monthly API call limit reached.

• Resolution: Upgrade to a higher plan or wait until quota resets.

• HTTP Status: 429 Too Many Requests

• Error Example:

  json

  {  "error": "rate_limit_exceeded",  "message": "You have reached your 10,000 call monthly limit."}

Recommended Retry and Fallback Patterns

• Retry: For transient network errors (5xx), retry up to 3 times with exponential backoff.
• Fallback: If a transformation fails, fall back to delivering the original file or a cached previous version.
• Graceful Degradation: For quota limits, surface a user-friendly message and a link to upgrade your plan.

Debugging with Tweekit API Request Logs

When using TweekIT in an MCP context:

1. The TweekIT API call requests are logged inside of your tweekit.io account under each key in use.
2. Your MCP requests return appropriate responses if they fail.
3. Review your console output where defined by you in your configuration of the MCP Server.

Advanced Topics

For teams pushing TweekIT beyond simple transformations, these advanced techniques can help you integrate deeper into AI pipelines, improve performance, and harden security.

Integrating with AI Pipelines

TweekIT can serve as the pre-processing layer for AI workflows, ensuring inputs are in the correct format and size before being fed to downstream models. Instead of errors or bad/non-existent conversions, just use tweekit, to make sure the file can be used as intended.

Examples

• Image-to-Video: Normalize all frames before passing them to a video synthesis model.
• Image-to-Image: Normalize any file, including the first page of any document or pdf, camera raw, tiff, psd, illustrator, etc. of any kind into a .png or .jpg that your LLM can handle.
• Style Transfer: Resize and reformat images to match the model’s expected input dimensions.
• OCR Pipelines: Convert documents to high-contrast PNGs to improve text recognition accuracy.
• Pro formats (ie. Adobe Illustrator) ingestion: Convert into usable image format for rendering a complex PDF document rather than failing, or receiving unusable results.
• Office Document, legacy and complex formats to PDF: Word files of all types (.doc, .docm, .docx, .dot, .ppt, .vso) can now be converted into a standard PDF to ingestible by most AI LLM’s.

In MCP, chain TweekIT transformations before invoking the AI model action.

Performance Tuning

• Reduce Output Size: Use fmt (rest) outfmt (MCP) and compression-friendly formats like webp for faster delivery.
• Minimize Transform Steps: Chain transformations into one request instead of multiple previews.

Security Hardening

• API Key Management: Rotate keys regularly and limit scope when possible.
• Reverse Proxy Secrets: Use a server-side proxy to inject credentials, keeping them out of the browser.
• CORS and Domain Restrictions: Configure your account to only accept widget calls from trusted domains.
• Short DocId Lifespans: Rely on the default 20-minute expiry to limit exposure of uploaded files. (only applies to Rest API’s - For MCP files are only used during lifetime of processing and then purged)

Registry Readiness

Preparing for MCP registries (Pulse, OpenAI, Anthropic, etc.)? Track the public requirements in docs/mcp-pulse-checklist.md. The checklist covers:

• Required artifacts (live endpoints, plugin proxy, Claude bundle, docs, changelog)
• Automated test expectations (pytest, optional staging sweeps)
• Operational policies (secrets, monitoring, rollback, SLA)
• Submission packet assets (screenshots, logs, support contact, license references)

Keep the outstanding tasks section current before every submission.

Resources

Use the links below for deeper technical reference, pricing details, and support.

• API Reference
  TweekIT REST API Documentation
  Full endpoint list, parameters, authentication methods, and sample code.

• Widget API Reference
  TweekIT Widget Documentation
  Constructor options, properties, methods, and event listeners.

• Pricing
  TweekIT Pricing Guide
  Free tier details, paid plan tiers, and overage rates.

• Claude Desktop Bundle Guide
  docs/claude-bundle.md
  Step-by-step packaging instructions, the configure_claude_desktop.py helper, and security context for our Tier 1 headless nodes.

• Search Tool & Remote Assets
  docs/quickstarts.md
  Explains how the DuckDuckGo-backed search tool helps you locate files before running convert_url, plus notes on swapping providers.

• Support Contact Email: [email protected] Submit tickets for technical help, account issues, or feature requests.

Solving Claude's File Type Limitations

The Problem: AI Tool File Ingest Restrictions

Claude, ChatGPT, and other AI tools have built-in file type limitations that prevent you from analyzing, extracting, or working with hundreds of common file formats. While Claude can read PDFs and common image formats (PNG, JPEG, WebP), it cannot directly process:

• Legacy Microsoft Office documents: DOC, XLS, PPT, and older binary formats
• OpenDocument formats: ODT, ODS, ODP
• Adobe files: PSD, AI, INDD
• CAD/Design files: DWG, DXF, SKP
• Specialized formats: EPS, TIFF, RAW camera files, proprietary formats
• And 400+ other file types

Note: While newer XML-based formats like DOCX, XLSX, PPTX may have better support, legacy binary Office formats (DOC, XLS, PPT) and specialized formats consistently cause issues.

This creates a frustrating workflow bottleneck: you have a file with valuable content, but your AI tool simply rejects it.

The Solution: TweekIT File Format Enabler

TweekIT MCP Server solves this problem by acting as a universal translator that converts any of 450+ file formats into Claude-compatible formats (PDF, PNG, JPEG, WebP). This means:

✅ No more "unsupported file type" errors ✅ Analyze content from ANY document format ✅ Extract text and data from legacy files ✅ Work with professional design files in AI workflows ✅ Convert office documents into AI-readable PDFs

AI File Format Enabler Web Tool

We've created a standalone web converter specifically designed to help users of Claude, OpenAI, and other AI tools overcome file type limitations:

Location: examples/web-converter/index.html

Purpose: Convert unsupported file types into AI-compatible formats (PDF, PNG, JPEG, WebP) before uploading to Claude, ChatGPT, or other AI tools

How to Use:

1. Open examples/web-converter/index.html in your browser
2. Enter your TweekIT API credentials (get free credentials at tweekit.io)
3. Upload ANY file format (DOC, XLS, PSD, AI, DWG, etc.)
4. Select output format (PDF, PNG, JPEG, or WebP)
5. Download the converted file
6. Upload the converted file to Claude

Common Use Cases:

• Legacy Word documents → PDF: Convert DOC files to PDF for Claude analysis
• Legacy Excel spreadsheets → PNG: Convert XLS to images for data visualization
• Legacy PowerPoint → PDF: Convert PPT presentations to PDF for content extraction
• Design files → PNG: Convert PSD, AI, or other design files to viewable images
• CAD files → PDF: Convert DWG/DXF files to PDF for technical review
• Proprietary formats → Standard formats: Convert specialized file types to universal standards

Integration with Claude Desktop

For seamless integration within Claude Desktop, install the TweekIT MCP server:

{  "mcpServers": {    "tweekit": {      "transport": { "type": "http", "url": "https://mcp.tweekit.io/mcp" }    }  }}

Then ask Claude to convert files directly:

"Use TweekIT to convert this DOC file to PDF so you can read it"

Claude will automatically call the TweekIT MCP server, convert the file, and return a Claude-compatible format.

Why This Matters

Before TweekIT: User uploads legacy DOC file → Claude rejects it → User manually converts → User re-uploads → Workflow broken

With TweekIT: User uploads DOC file → Claude calls TweekIT → File converted to PDF → Claude reads it → Seamless workflow

This eliminates the frustration of file format limitations and enables Claude to work with virtually any file type.