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.3

🤖 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](examples/web-converter/) – 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
• On-Premises & Localhost Processing via Miner Renderery
• 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 pip

pip install tweekit

Using uv

uv pip install tweekit

Run directly as an MCP server with zero local setup via uvx

uvx 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 asyncio

from pathlib import Path from 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.git

cd tweekit-mcp uv 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: Configure Credentials Securely (Environment or HTTP Headers Only)

TweekIT MCP authenticates using your API Key and Secret configured in MCP client headers (for hosted Streamable HTTP) or TWEEKIT_API_KEY / TWEEKIT_API_SECRET environment variables (for local stdio).

Security Rule: Never place TWEEKIT_API_KEY or TWEEKIT_API_SECRET inside natural-language prompts or LLM tool-call arguments. Credentials are intentionally excluded from MCP tool schemas so they never appear in model context or conversation logs.

Step 3: Make Your First API Call

Once your MCP client is configured with ApiKey and ApiSecret HTTP headers (or TWEEKIT_API_KEY / TWEEKIT_API_SECRET environment variables), call convert with only document and geometry arguments:

{

"method": "tools/call", "params": { "name": "convert", "arguments": { "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 & B