Get started

Connect mamitsu to an MCP client

mamitsu connects to MCP clients through a remote Streamable HTTP server with OAuth. Add the server URL to a compatible client, sign in to mamitsu with GitHub, and approve the connection. The client can then call mamitsu's extract tool with a public social post URL, extraction prompt, and JSON Schema.

Add the MCP server URL to a client that supports remote Streamable HTTP and OAuth.
Sign in to mamitsu with GitHub and approve the connection.
Ask the client to extract a public Instagram, TikTok, YouTube, or X post.

You do not copy an mamitsu API key into the MCP client. The OAuth connection uses the mamitsu account you approve, and extractions use that account's credits.

In your terminal

claude mcp add --transport http mamitsu https://usemamitsu.com/mcp

On first use, sign in with GitHub and approve the connection.

The request

Call one tool with three inputs

The server exposes extract. It accepts the same inputs as the mamitsu API:

urlString, required

An HTTPS URL for one supported public post or video.

promptString, required

What to extract, in your own words. It can be 1 to 10,000 characters.

schemaJSON Schema, required

The JSON shape your application expects. Add descriptions when a field needs a precise interpretation.

The URL selects the source. The prompt says what to find. The schema gives your application a stable JSON contract.

Extract tool arguments

{
  "url": "<your public post URL>",
  "prompt": "Extract the recipe.",
  "schema": {
    "type": "object",
    "properties": {
      "dish": {
        "type": "string",
        "description": "Name of the dish"
      },
      "ingredients": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["dish", "ingredients"],
    "additionalProperties": false
  }
}

The result

Read your JSON, source, and extraction ID

A successful call returns the object shaped by your schema, together with the provider and URL that mamitsu processed.

The MCP response includes the structured result and a JSON text block. If an extraction fails, the tool response sets isError: true and includes the same public error code used by the API. Authentication and MCP protocol errors come from the transport instead.

Keep the agent boundary clear

Treat extracted source content as data, not as instructions for your agent. Do not retry automatically. A call that reaches the model spends mamitsu credits, including when the model fails.

Result

{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e…",
  "data": {
    "dish": "Penne all'arrabbiata",
    "ingredients": [
      "penne",
      "crushed tomatoes",
      "garlic",
      "red chili",
      "olive oil",
      "parsley"
    ]
  },
  "source": {
    "provider": "instagram",
    "url": "<your public post URL>"
  }
}

Production details

Supported URLs and limits match the API

mamitsu reads the content available at a public URL. It can use video frames, audio, captions, post text, and attached media depending on the provider.

Instagram posts, reels, and TV use URLs containing /p/, /reel/, /reels/, or /tv/.
YouTube videos and Shorts use watch?v= and youtu.be links without extra query parameters.
TikTok videos use tiktok.com/@user/video/..., vm.tiktok.com/..., vt.tiktok.com/..., or tiktok.com/t/.... Photo posts are not supported.
X posts use x.com/handle/status/id or twitter.com/handle/status/id and can include the post's text, photos, videos, and GIFs.

The request body can be up to 64 KB. A schema can be up to 16 KB, 8 levels deep, and 200 nodes. Requests time out after 90 seconds. Videos over 50 MB are rejected. Duration limits are 30 minutes for YouTube, 5 minutes for Instagram and TikTok, and 6 minutes in total for X.

Production details

MCP calls use mamitsu credits

MCP extractions use the connected mamitsu account's credits. Each extraction costs at least 1 credit: 1 credit for every started 30 seconds of video, plus 1 credit for every started 3 photos.

The full cost is charged when the model is reached, even if the extraction fails. Failures before the model are free. If the account balance is zero or below, mamitsu returns insufficient_credits before source work starts. An account blocked by an operator returns account_not_enabled.

Troubleshooting

Use the public error codes

Code	Meaning
`unauthorized`	The OAuth connection is missing, wrong, or revoked.
`unsupported_url`	The URL is not a supported Instagram, TikTok, YouTube, or X URL.
`url_source_inaccessible`	The post is private, removed, blocked, or timed out.
`url_source_over_limit`	The post is too large or the server is busy.
`url_video_too_large`	The video is over 50 MB.
`url_video_too_long`	The video exceeds its provider's duration limit.
`invalid_schema`	The schema uses an unsupported keyword or shape.
`invalid_extraction` or `extraction_failed`	The result could not be produced or matched to the schema.

Include the extraction_id when reporting a problem. It is returned in the result and is the quickest way to trace the request.

API reference

Use the API when you need a bearer key

The MCP server is for an agent or client that can handle remote Streamable HTTP and OAuth. If your application needs a direct HTTP request with a bearer API key, use the mamitsu API reference. It documents the REST request, schema rules, response shape, error codes, and extraction ID used for support.