Tweekit Logo
Home Demo Use Cases Pricing Documentation MCP Server

Welcome,

Logout

Home

TweekIT MCP Server - Ingest and Convert Just About Any Filetype Into AI Workflows

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

Example scenario

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

  1. Convert the PDF to a PNG image
  2. Crop to just the ID card
  3. Resize to a standard 300x300 pixel headshot
  4. 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 450+ file types for seamless ingestion and conversion, leveraging a core engine refined over two decades to handle dynamic imaging and video delivery.
  • 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

New in MCP Server 1.5

  • convert_url now streams remote files over HTTP(S) straight into the TweekIT pipeline, with optional fetchHeaders for authenticated sources.
  • Automatic extension detection plus richer error payloads (including TweekIT debug headers) simplify troubleshooting inside agents.
  • A new config://tweekit-mcp-version resource tracks the deployed MCP build alongside the upstream API version.
  • Fresh quickstarts cover Cursor and Continue IDEs so teams can register the hosted server with just a few lines of JSON.

Hosted MCP Server

Use our hosted MCP server immediately — no setup required. Point your MCP client at:

https://mcp.tweekit.io/mcp/

Currently available:

  • Resources: config://tweekit-version, config://tweekit-mcp-version
  • Tools: doctype, convert, convert_url, search, fetch

Quickstarts

Containerized Server (Docker)

Bundle the MCP server with your own services. Build and run the container shipped in tweekit-mcp:

git clone https://github.com/equilibrium-team/tweekit-mcp.git
cd tweekit-mcp
docker build -t tweekit-mcp .
docker run --rm -p 8080:8080 \
  -e TWEEKIT_API_KEY=YOUR_KEY \
  -e TWEEKIT_API_SECRET=YOUR_SECRET tweekit-mcp

Point local tooling at http://localhost:8080/mcp/ (or your reverse proxy) before promoting configs to staging or production.

Claude Desktop

Add this to your Claude MCP configuration:

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

Example tool call (base64 shortened):

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

ChatGPT MCP (HTTP)

Point ChatGPT’s MCP tools at the same endpoint and use built-in tools:

{ "name": "search", "arguments": { "query": "tweekit", "max_results": 3 } }
{ "name": "fetch",  "arguments": { "url": "https://tweekit.io" } }

Cursor IDE

Cursor loads MCP servers from ~/.cursor/mcp.json. Merge the snippet below (also in our repo at configs/cursor-mcp.json) and restart Cursor:

{
  "mcpServers": {
    "tweekit": {
      "type": "http",
      "url": "https://mcp.tweekit.io/mcp/",
      "headers": {
        "ApiKey": "${TWEEKIT_API_KEY}",
        "ApiSecret": "${TWEEKIT_API_SECRET}"
      }
    }
  }
}
  1. Export TWEEKIT_API_KEY and TWEEKIT_API_SECRET (or replace the placeholders with literal values).
  2. Run “List tools” in Cursor to confirm version, doctype, convert, and convert_url are available.
  3. Optional: host the JSON internally and expose an “Add to Cursor” deep link for teammates.

Continue IDE

Continue stores MCP entries in ~/.continue/config.json. Add the hosted 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}"
      }
    }
  }
}
  1. Reload Continue so it picks up the new server entry.
  2. Invoke tools from the Continue panel—doctype, convert, and convert_url share the same arguments shown above.
  3. Document credential handling (environment variables, secret storage) so teammates can connect quickly.

OpenAI TypeScript (MCP SDK)

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: "search", arguments: { query: "tweekit", max_results: 3 } });
// Need remote ingestion? call convert_url with { url, outfmt, fetchHeaders }.
console.log(res);

Python Quick Call

import asyncio
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("fetch", {"url": "https://tweekit.io"})
        print(out)

asyncio.run(main())

ChatGPT Plugin Proxy

Ship a GPT-style experience using the FastAPI proxy in plugin_proxy.py. Publish /.well-known/ai-plugin.json, import the URL inside ChatGPT’s “Actions” panel, and authenticate with either a bearer token (your TweekIT API key) or X-Api-Key/X-Api-Secret headers.

  • Configure PLUGIN_PUBLIC_BASE_URL, logo, and support links to match your TLS domain.
  • Verify /openapi.json plus /version, /doctype, and /convert succeed before submission.
  • Rotate credentials by updating proxy environment variables—no client rebuild required.

See our MCP Evals Report here to review the latest automated checks against the hosted server.

DeepSeek Bridge

DeepSeek does not yet expose native MCP hooks. Use the bundled bridge script to normalize files before calling the DeepSeek API:

python scripts/deepseek_mcp_bridge.py \
  --file input.pdf \
  --outfmt txt \
  --server https://mcp.tweekit.io/mcp/ \
  --api-key $TWEEKIT_API_KEY \
  --api-secret $TWEEKIT_API_SECRET \
  --output converted.txt

Embed the workflow inside agents or CI jobs so every request delivers AI-ready text or imagery before DeepSeek continues the conversation.

Grok (xAI) Readiness

Grok lacks a public MCP interface today, but the release documents how to get started:

  • Load https://mcp.tweekit.io/mcp/ via MCP-capable browser extensions (such as MCP SuperAssistant) to expose TweekIT tools within Grok.
  • Document command palette or slash-command flows so operators can trigger convert or convert_url in conversations.
  • Reuse the ChatGPT proxy manifest once xAI opens an official plugin or MCP registry.

Minimal JSON-RPC Example

Captured from MCP Inspector calling the public server:

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "png",
      "outfmt": "png",
      "blob": "iVBORw0K...",
      "noRasterize": false,
      "width": 30,
      "height": 30,
      "page": 1,
      "bgcolor": ""
    }
  },
  "jsonrpc": "2.0",
  "id": 4
}

Need to transform a file that already lives behind HTTP? convert_url skips the base64 step and can forward authentication headers:

{
  "method": "tools/call",
  "params": {
    "name": "convert_url",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "url": "https://example.com/uploads/brochure.pdf",
      "outfmt": "png",
      "page": 1,
      "width": 1024,
      "fetchHeaders": {
        "Authorization": "Bearer ${ACCESS_TOKEN}"
      }
    }
  },
  "jsonrpc": "2.0",
  "id": 5
}

Client Compatibility

  • Claude (Desktop): Compatible (HTTP transport; discovers tools via listTools).
  • ChatGPT (OpenAI): Compatible (HTTP transport; includes the bundled search and fetch tools).
  • Cursor IDE: Supported via the JSON config shown above.
  • Continue IDE: Supported via streamable-http transport (see quickstarts).

Try it now:

  • Live Demo – Upload and transform files in your browser
  • View Use Case Examples for real workflows and code samples on the website. The specific MCP manifest conversions are shown in section 7 below.

Requirements

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

Installation

Clone the repository:

git clone https://github.com/equilibrium-team/tweekit-mcp.git
cd tweekit-mcp

Install dependencies

pip install -r requirements.txt

Set up environment variables:

PORT: The port on which the server will run (default: 8080).

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 access your API credentials and start using the service.

Step 2: Choose Your Authentication Method

The hosted MCP server expects the API Key + Secret pair from your TweekIT account. Generate them in the Manage Account dashboard, load them via environment variables or a reverse proxy, and keep them out of client-side code.

If you currently use the legacy AppID flow for REST calls, note that it is not accepted by Model Context Protocol clients.

Step 3: Make Your First API Call

Your MCP client can now issue JSON-RPC calls like the convert and convert_url examples above. If you need to validate the underlying REST workflow manually, the Node.js snippet below uploads a file, previews it, and downloads the result using the same credentials.

const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');

const headers = {
  apikey: '{Your API Key}',
  apisecret: '{Your API Secret}'
};

async function uploadFile(filePath, fileName) {
  const url = 'https://dapp.tweekit.io/tweekit/api/image/upload';
  const formData = new FormData();
  formData.append('name', fileName);
  formData.append('file', fs.createReadStream(filePath));

  const response = await fetch(url, { method: 'POST', headers, body: formData });
  const docID = response.headers.get('x-tweekit-docid');
  return docID;
}

async function previewImage(docID) {
  const url = `https://dapp.tweekit.io/tweekit/api/image/preview/${docID}`;
  const options = {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json;charset=UTF-8' },
    body: JSON.stringify({ width: 300, height: 300, fmt: 'png' })
  };
  const response = await fetch(url, options);
  const buffer = await response.buffer();
  fs.writeFileSync('output.png', buffer);
}

(async () => {
  const docID = await uploadFile('example.jpg', 'example.jpg');
  await previewImage(docID);
  console.log('Transformation complete. File saved as output.png');
})();

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