Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Poster MCP Quote a vertical 2:3 café opening poster with headline 'Grand Opening' and show exact credits."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Poster.sh is an AI Poster Generator that turns a text brief into a poster. This MCP server lets your AI assistant get an exact quote, create a poster after your approval, and retrieve your own result.
Use it for café openings, event announcements, product launches or promotional posters. Describe the message and visual direction in your assistant; Poster returns the actual preview URL and structured poster document when the task is ready.
Four tools · Local stdio · Your own Poster API Key · MIT adapter
Website · API Keys · Releases · Report an issue
Requires Node.js 20.10+ with npm/npx and an MCP client that can launch local stdio servers. This is not a remote HTTP connector: do not enter poster.sh as an MCP endpoint. Your assistant runs this adapter locally and it calls the existing Poster HTTPS API.
Sign in to Poster.sh API Keys and use your own existing key. Generation uses that account's balance.
Paste the configuration below into your client's private local MCP settings, replacing only the key placeholder. Clients using mcpServers JSON, including Claude Desktop and Cursor, can use this format.
Restart or reconnect your client's MCP server. Check that the four tools below appear, then ask for a quote. Quoting does not generate a poster or spend credits.
{
"mcpServers": {
"poster": {
"command": "npx",
"args": [
"--yes",
"--package=https://github.com/aistudy11/poster-mcp/releases/download/v0.1.2/poster-sh-mcp-0.1.2.tgz",
"poster-mcp"
],
"env": {
"POSTER_API_KEY": "YOUR_POSTER_API_KEY"
}
}
}
}This installs the versioned official GitHub release automatically; no private product checkout, global package install or absolute script path is needed. The first start downloads dependencies, so allow it to finish. npx needs network access during installation.
Enable generation deliberately: the configuration above allows quotes and reads but blocks new creation. To allow creation, add POSTER_MAX_CREDITS_PER_POSTER to env with your chosen integer limit as a string (for example "10" means a ceiling of 10 credits per new poster, not a price quote). If the actual quote exceeds your limit, creation is refused. It is a per-poster ceiling, not a daily or account budget. Your assistant must still show the exact prompt, selection and cost and ask for approval before creating. Do not auto-approve create_poster or advance_poster.
Try this first: “Quote a vertical 2:3 poster for a café opening, with the headline 'Grand Opening', warm terracotta colors and a simple modern layout. Show me the exact credits before generating.” A quote returns a request and its current cost. Only approve creation once you have checked them; a pending task is not a completed poster.
Related MCP server: PostcardAI MCP Server
The standalone source is published at aistudy11/poster-mcp. For contributors or a fixed local checkout:
git clone https://github.com/aistudy11/poster-mcp.git
cd poster-mcp
pnpm install --frozen-lockfileFor a source checkout, validate it with:
pnpm check
pnpm testAlternatively, configure that source checkout directly. Replace the path and key with your own values in the client's private local settings, never in a public repository or directory submission:
{
"mcpServers": {
"poster": {
"command": "node",
"args": ["/absolute/path/to/poster-mcp/cli.mjs"],
"env": {
"POSTER_API_KEY": "your-existing-poster-api-key"
}
}
}
}Use an existing key from your own Poster API Keys page. The key is sent only to the configured Poster origin as X-API-Key. No website cookies or shared operator account are needed for ordinary use. This directory is independent of the Next.js installation and its dependencies.
Both default configurations permit quoting and reading while new creation is disabled. To enable creation, explicitly configure POSTER_MAX_CREDITS_PER_POSTER to the maximum credits you approve for each new poster. This is a per-request limit, not a daily or account spending budget. Each creation still requires the user's explicit approval of the actual quoted prompt, selection and credits in the MCP client. Do not configure automatic approval of create_poster or advance_poster.
Advancing an existing job is a separate mutating operation, available only with confirmed: true. It can perform recovery attempts within the original job's budget and settle that job's frozen price. The new-creation cap does not change or limit an already accepted job's price. Only advance a job whose original operation and cost were approved; if that approval is unavailable, read it with get_poster and ask the user before continuing. No new creation cap or quote authorizes an old job's settlement.
Variable | Behavior |
| Required for business calls; without a key, only MCP discovery is available. Use your existing personal Poster key. Never pass it as tool input or a URL parameter. |
| Optional HTTPS origin; defaults to |
| Optional nonnegative integer. Omitted disables creation; quotes and existing results remain available. Zero permits only a genuinely zero-credit quote. |
| Optional positive integer, default 15000. A timeout does not prove a submission failed. |
Tool | Existing API | Effect |
|
| Free authenticated quote. Returns the actual model, selection, credits and an exact request with a UUID. |
|
| Potentially paid. Requires |
|
| Read-only owned task/result. |
|
| Requires |
Example conversation:
“Quote a 2:3 poster for our café opening.” The client calls quote_poster with the brief and optional selection. Omitted model/quality/ratio values are resolved by Poster, not guessed locally.
Show the returned prompt, model, ratio and credits. Ask the user to approve the actual operation and cost.
After explicit approval and with the configured limit, call create_poster with the returned request unchanged and confirmed: true.
If the result is planning or generating, use advance_poster with its existing ID and confirmed: true only under the original job/cost approval. These states are pending; do not report an image as completed. Use get_poster when only reading status.
When the API returns ready, return its real previewUrl, document and other result fields. get_poster can reopen the same owned result. Private results stay subject to the existing API's ownership check; do not submit them to a public directory.
This initial adapter exposes the supported text-to-poster flow. It does not add editing, uploading, batch generation or translation tools. The existing website and QRCodeBrain capabilities remain available through their existing paths.
No Poster tools? Check that Node/npm are installed and available to your desktop app, that the release URL is copied in full, and that the client supports local stdio. Restart the MCP connection and inspect its server log. If the desktop app cannot find npx, use its absolute executable path from your Node installation.
Can I use it in browser-only ChatGPT? This release requires a client that can launch a local stdio process. It does not publish a remote MCP URL or OAuth connector.
Is it free? The adapter is MIT licensed. Quotes and reads do not spend generation credits; poster creation uses your Poster account's actual quoted credits. Continuing an approved existing job can perform recovery and settle its original price.
What comes back? A task ID and state; once ready, the actual previewUrl, structured document and other API result fields. The initial adapter has no editing, upload, translation or batch tools. The website's editor is a separate existing product capability.
Where does my key go? It stays in your private client settings and is sent only to the configured Poster origin. Never paste a real key into a directory, issue, example prompt or shared configuration.
API_KEY_REQUIRED: tool discovery is available, but no Poster API request is sent until you configure your own key.
CREDIT_LIMIT_REQUIRED: no creation cap configured; no submission was sent.
CREDIT_LIMIT_EXCEEDED: the approved quote exceeds the configured cap; no submission was sent.
POSTER_HTTP_400/409: the existing API refused the request; quote the intended selection again when the price or input needs correcting. Do not retry indefinitely.
POSTER_HTTP_401/403: the key or permission is not accepted.
POSTER_HTTP_402: the key owner's Poster balance is insufficient. This adapter does not create a new billing system.
POSTER_HTTP_404: unavailable or non-owned result; do not infer another user's data exists.
POSTER_HTTP_429/503: respect the service's refusal and retry deliberately; no automatic paid resubmission is performed.
REQUEST_OUTCOME_UNKNOWN: the response was lost or timed out. Preserve the original UUID and exact complete request. Read/advance a known task ID, or explicitly retry that same request. Never invent a replacement UUID to recover an uncertain purchase.
INVALID_POSTER_RESPONSE: malformed or incomplete output, including a false ready with no actual result; never presented as success.
The API remains authoritative for quote changes and idempotent retries. Credential-bearing redirects are refused. Arbitrary upstream error text is not returned to the AI client. Stdout carries only MCP protocol messages; startup diagnostics use sanitized structured stderr.
pnpm test uses the official MCP SDK client over a real child-process stdio transport and a controlled local HTTP API fixture. It proves adapter wiring, body preservation, confirmation/cap boundaries, error propagation and credential-safe redirects. The fixture is not a production generation or billing receipt. Production checks and release results belong to the project's current development checklist; do not claim they passed merely because local tests passed.
Create a reviewable installation archive with:
pnpm pack --pack-destination /absolute/path/to/outputThe independently written adapter is distributed through the public GitHub repository under the included MIT license. private: true prevents accidental npm publication; it does not prevent cloning or installing this public repository. No npm registry package or remotely hosted MCP endpoint is claimed.
Only this adapter directory is distributed. The parent product repository, licensed template source, .env files, API keys and private acceptance records are excluded. The product repository maintains the canonical adapter; the standalone repository is its distribution snapshot, not a separately developed business implementation. A directory submission, publication and a publicly visible backlink are separate states.
SDK dependency pinned to @modelcontextprotocol/sdk@1.32.1, using its real McpServer, registerTool, StdioServerTransport and StdioClientTransport APIs.
JSON Schema in MCP tool inputs is validated by the SDK. This package does not modify website Schema.org JSON-LD.
MUTATING ACTION: continue an existing owned job only with explicit approval of that job and its original cost. The existing API may perform recovery attempts within that job budget, save results and settle its frozen approved price. This does not create a separate poster request. The new-creation credit cap does not reprice an accepted job. Use get_poster for read-only status. Do not replace a failed job automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| confirmed | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds real context beyond them: recovery attempts occur within the existing job budget, results are saved, the frozen approved price is settled, and no re-pricing happens. It stops short of saying what the tool returns or what happens when the job cannot be advanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The mutating-action warning is front-loaded and each sentence carries substantive information about behavior or billing. A couple of clauses ('new-creation credit cap does not reprice an accepted job') are tangential and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only two boolean/string parameters, the description covers the essential concerns: mutation semantics, approval requirement, budget/billing scope, and the read-only alternative. It leaves the return value and failure behavior unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters, so the description must carry the load. 'Explicit approval of that job' reasonably maps to the `confirmed: true` const, but the `id` parameter's meaning (which kind of job/owner identifier) is never addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (continue/advance an existing owned job) on a specific resource, and explicitly distinguishes it from creating a new poster request. It is clear without opening the schema, though the front-loaded jargon ('advance', 'settle frozen approved price') is somewhat domain-heavy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit precondition ('only with explicit approval of that job and its original cost'), names the read-only alternative ('Use get_poster for read-only status'), and states a prohibition ('Do not replace a failed job automatically'). When-to-use, when-not, and the alternative are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ACTION: submit the exact quoted request only after the user approves its prompt, selection and quoted credits. Requires the operator-configured per-poster credit limit. Reuse the identical requestId and payload after uncertainty; never silently create a replacement task. A planning/generating response is pending, not a finished poster.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | ||
| confirmed | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safety profile (not read-only, idempotent, non-destructive, open-world); the description adds the material behavior: this costs credits, it requires a pre-configured credit limit, it is approval-gated, and a planning/generating response is a pending task rather than a finished poster. This goes well beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all load-bearing, with the highest-stakes information ('PAID ACTION') front-loaded. No restatement of the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async, paid creation tool with no output schema, the description covers cost, approval prerequisites, idempotent retry, and the pending-vs-finished distinction. The one gap is that it never points the agent at get_poster/advance_poster for tracking the pending task, though the sibling names are visible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and a nested request object, the description carries the load and does explain the key fields semantically: prompt and selection must be the quoted ones, quotedCredits must match the user-approved quote, and confirmed is effectively the 'user approved' gate. It does not explain the remaining request fields (model, vendor, quality, styleId, aspectRatio), so it is meaningful but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (submit a quoted request that creates a poster) and flags it as a paid action up front. It implicitly ties to the quoting flow via 'the exact quoted request' but never names the sibling quote_poster, so the differentiation from quote_poster/advance_poster is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit gate: submit only after the user approves prompt, selection and quoted credits, and only within the operator-configured per-poster credit limit. It also states the recovery rule (reuse the identical requestId and payload after uncertainty; never silently create a replacement task), which is exactly the when/when-not guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an existing owned poster and its current state. A ready response includes the actual previewUrl and document. Does not advance a task, create images or charge. Non-owned IDs remain refused by the existing API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them: what a ready response contains (previewUrl, document), that it is free ('does not charge'), that it has no task side effects, and that non-owned IDs are refused by the API.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core purpose, then return content, then side-effect scope. No filler or restated boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the payload fields returned when the poster is ready, and it discloses the ownership precondition and absence of side effects. Minor gap: it does not describe non-ready/error states beyond the ownership refusal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required uuid parameter, so the description must carry the meaning. It does add semantics: the id must reference a poster the caller owns, and non-owned IDs are rejected by the API — a constraint not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read an existing owned poster and its current state') and scopes it to owned posters. The negations ('Does not advance a task, create images or charge') implicitly separate it from the sibling tools advance_poster and create_poster, so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the negation clause tells the agent this is not the mutating/creating path, and 'Non-owned IDs remain refused' sets a precondition. But there is no explicit 'use this when X, use quote_poster/create_poster when Y' routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the actual price and supported selection from Poster, without generating or charging. Return an exact request to show the user and pass unchanged to create_poster after explicit approval. Models, sizes, availability and prices come from the API.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| prompt | Yes | ||
| vendor | No | ||
| quality | No | ||
| styleId | No | ||
| aspectRatio | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), yet the description adds real behavioral context: no side effects, no billing, and a contract that the returned payload must be passed unchanged to create_poster. A note on freshness/expiry of the quote would have pushed this to a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, no filler, with the core purpose front-loaded and the downstream workflow second. Every sentence adds a distinct piece of information (what it reads, what it returns, where the values originate).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description adequately characterizes the return value as an exact request the agent should display and then forward. Combined with annotations covering the read-only safety profile, the main remaining gap is the undocumented parameter semantics, which is significant but not fatal for a quote-before-create flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across six parameters (model, prompt, vendor, quality, styleId, aspectRatio), so the description carries the full documentation burden. It only hints that models, sizes and prices 'come from the API', giving no syntax, defaults, or expected values for any parameter. This is a substantial gap for a 6-param tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read/quote) and resource (Poster price and supported selection) and immediately distinguishes itself from the sibling create_poster by clarifying it does no generating or charging. An agent can tell from the text alone that this is a dry-run pricing call, not a write.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly sets the workflow: quote first, show the user, then pass the returned request unchanged to create_poster after explicit approval. The phrase 'without generating or charging' functions as the when-not-to-use condition that routes generation to create_poster. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2advance_postercreate_posterget_posterquote_posterScored across 4 tools
Each tool occupies a distinct phase of the poster lifecycle: quote is read-only pricing, create is the paid submission, get is read-only status, and advance mutates an existing owned job. The descriptions explicitly clarify boundaries, especially quote vs. create and get vs. advance.
All four tools follow the same snake_case verb_noun pattern with a consistent noun: quote_poster, create_poster, get_poster, advance_poster. The verbs are distinct and predictable.
Four tools are well-scoped for a focused quote-create-read-advance workflow. There is no obvious bloat, and each tool has a clear role in the pipeline.
The core lifecycle is covered: quote a request, create after approval, read status, and advance an existing job. Minor gaps remain around listing owned posters, cancellation, or refund/delete paths, which agents may need in edge cases.
Generate and edit images, create videos, quote credit costs, and retrieve private results.
Access Pollinations models and API capabilities through agent tools.
Create AI images and videos, manage projects and credits, and use workspace campaign context.
Generate images, videos and music with model discovery, cost estimates and asynchronous results.
