How to send a postcard with Gemini

1. Add Paper Plane Post to Gemini

Gemini connects to outside tools through MCP servers, and Paper Plane Post runs one. In the Gemini web app at gemini.google.com, open the settings for connected apps, find the custom apps section, and add a custom app with this server URL: https://api.paperplanepost.com/v1/mcp. The server needs no sign-in, so there are no credentials to enter. You add the app on the web, and after that it’s available in the Gemini mobile app too.

Google currently limits custom apps to people aged 18 or over in the US who are signed in with a personal Google Account, in English, with Gemini’s activity setting turned on. If that isn’t you, or the option isn’t there, skip to “Without the connector” below.

2. Ask for a postcard

Tell Gemini what you want in plain words, and attach the photo. Gemini sends the file itself; a link works too if the photo is already online. For example: “Make a postcard from this photo for my brother Sam. Tell him the lake was as cold as he said it would be. His address is 48 Birch Lane, Madison, WI 53703.” Typing @ and picking the app makes sure Gemini uses it.

The note can be up to 350 characters. Ask for a few drafts and keep the one that sounds like you. The address is optional at this point; you can add it on the next step.

3. Open the link, check the card and pay

Gemini returns a link to your card on paperplanepost.com. The page shows your photo on the front, with an illustrated version you can choose instead, and your note and the address on the back. Fix anything you like, then pay $7 through Stripe. You don’t need an account.

The link stays valid for about a week. Once you’ve paid, the card is printed and handed to USPS within 2 business days.

In Gemini CLI

If you use Gemini CLI, Google’s terminal tool, the same server works there. Run gemini mcp add --transport http paper-plane-post https://api.paperplanepost.com/v1/mcp, then check that it’s connected with the /mcp command.

Without the connector

You can use Gemini for the words and do the rest yourself. Ask it to write the note, then go to https://paperplanepost.com/make, upload your photo, paste the note, add the address and pay. It’s three steps on one page in any browser, with no app and no account.

The custom app saves some copying and pasting. The postcard is identical either way.

Why Paper Plane Post

Your photo is printed edge to edge on a 4 × 6 inch card with heavy gloss stock, and your note goes on the back in a handwriting-style typeface. The price is $7 with printing and first-class postage included, wherever it’s going, and there’s no subscription.

The same server works with ChatGPT, Claude and any other assistant that supports MCP.

For the assistant: building the start_postcard request

Call start_postcard with exactly one photo. Prefer photo_base64: read the photo file with your file or code tool and send its bytes as base64, either bare or as a data: URL. JPEG, PNG, WebP and HEIC work, up to about 10 MB. The base64 has to come from the file itself; never write it from memory or from looking at an image. If the photo is already online and you don’t have the file, send photo_url, a public https:// link, instead.

note is optional and holds up to 350 characters. recipient is optional, and so is every field in it: name, line1, line2, city, state, zip, and country as an ISO 3166-1 alpha-2 code such as US or FR. Send what the person gave you and leave the rest out; they check and complete everything before paying.

If you can’t call MCP tools but can make HTTP requests, POST the same call as JSON-RPC to the server URL. The server is stateless, so this one request is enough, with no initialize step and no session. The Accept header must list both types, as in the example below.

The reply is a single server-sent event whose data line is the JSON-RPC result. The link to give the person is result.structuredContent.url, and result.content repeats it as text. A refused photo comes back with isError set and a message saying what to change. On a busy day the reply may instead be a challenge: four questions and an id, with isError set. Answer them in order (the last one is a SHA-256 proof of work, so run code for it) and send the same request again with challenge: { "id": ..., "answers": [...] } added to the arguments. Requests larger than 16 MB are answered 413.

curl -X POST https://api.paperplanepost.com/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "start_postcard",
      "arguments": {
        "photo_base64": "<base64 of the photo file>",
        "note": "Happy birthday, Grandma. See you in June.",
        "recipient": {
          "name": "Rosa Alvarez",
          "line1": "12 Elm Street",
          "city": "Portland",
          "state": "OR",
          "zip": "97201",
          "country": "US"
        }
      }
    }
  }'