mamitsu

All guides

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 and extraction prompt, with an optional JSON Schema for a fixed result shape.

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

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

Install the mamitsu agent instructions from GitHub, then choose a client. Manage connected apps on Connect your agent.

MCP server

URL: https://usemamitsu.com/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.1

Install in Claude Code

Extract from social posts with mamitsu and its skills.

In your terminal

claude plugin marketplace add usemamitsu/agent-plugins &&
claude plugin install mamitsu@mamitsu &&
claude mcp login plugin:mamitsu:mamitsu

Connect your account

1. The command installs mamitsu and opens your browser for sign-in.
2. Sign in to mamitsu with GitHub and approve the connection.

The request

Call one tool with two required inputs and an optional schema

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

url String, required

An HTTPS URL for one supported public post or video.

prompt String, required

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

schema JSON Schema, optional

Define a fixed JSON shape for your application. Without it, mamitsu chooses descriptive fields and types from the prompt.

The URL selects the source. The prompt says what to find. Add a schema when your application needs a stable JSON contract; otherwise, mamitsu chooses the structure. Missing requested scalar facts are null; requested collections with no observations are [].

Fixed result shape

{
  "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
  }
}

Structure chosen from the prompt

{
  "url": "<your public post URL>",
  "prompt": "Extract the recipe."
}

The result

Read your JSON, source, and extraction ID

A successful call returns the object shaped by your supplied schema, or by the prompt when no schema was supplied, 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

New accounts start with 200 free credits. During the early access launch offer, purchases get 2 credits per cent. See pricing.

MCP extractions use the connected mamitsu account's credits. Each extraction costs at least 1 credit: 1 credit for every started minute of video, plus 1 credit for every started 3 photos. For YouTube, the first 5 minutes cost 1 credit per started minute, then each started 5-minute block costs 1 credit.

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 was not a JSON object or did not match a supplied schema, or the extraction failed.

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.