Skip to main content
Glama
feodor-ra

printables-mcp

printables-mcp

English · Русский

PyPI - Version PyPI - Python Version PyPI - Status CI

An MCP server for Printables.com: lets an AI agent search 3D models, read model cards, list files and get direct download links.

It talks to the public Printables GraphQL API directly: no HTML scraping, no browser, no account. All tools are read-only and return structured results (JSON with an output schema), so agents get exact fields instead of prose.

Installation

uv tool install printables-mcp

Then register the printables-mcp command with your MCP client. Claude Code:

claude mcp add printables -s user -- printables-mcp

Any other client that speaks stdio:

{
  "mcpServers": {
    "printables": { "command": "printables-mcp" }
  }
}

Without installing: uvx printables-mcp.

Related MCP server: PrintVaultMCP

Tools

Tool

What it does

search_models

Text search with pagination (limit, offset, total count) and filters: category, price (free / paid), licenses, published within N days, has user prints. Orderings: best match, popular, latest, rating, makes count.

get_model

Full model card: description as Markdown, tags, category path, license, materials, printer, print time, filament weight, images, PDF, remix sources, stats, price.

list_model_files

Every file group in one request: model files (STL/3MF/STEP…), G-code with printer, material, layer height, nozzle and print time, SLA files, other files, ZIP packs.

get_download_links

Direct download URLs (valid 24 h) for all or selected files, fetched in parallel. Files of paid or club-only models come back with a per-file reason instead of failing the call.

list_categories

All categories with their full paths (IDs for the search filter).

list_licenses

All licenses (IDs for the search filter).

get_author

Author profile by ID, handle or profile URL.

list_author_models

An author's models, cursor-paginated, ordered by newest, oldest, likes, downloads, rating or makes.

Models and authors can be passed as IDs or as printables.com URLs (locale prefixes such as /de/ are fine).

Limitations

  • Anonymous access only: paid and Printables Club models are visible, but their files cannot be downloaded.

  • The API is undocumented and may change without notice; the end-to-end suite (just test-live) checks it against the live service.

Development

uv sync
just lint       # ruff format/check + ty
just test       # pytest with 100% branch coverage
just test-live  # end-to-end tests against the real API

License

MIT

Available Tools

8 tools
get_authorC
Read-onlyIdempotent

Get an author's public profile.

Returns:
    The profile.
NameRequiredDescriptionDefault
authorYesUser ID ("16"), handle ("Prusa3D" or "@Prusa3D") or profile URL

Output Schema

NameRequiredDescription
idYes
bioYes
urlYes
nameYesPublic display name
handleYes
followersYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is fully covered. The description adds only the word "public" — it doesn't say what happens when the author doesn't exist or is private, nor does it note rate/visibility limits, so value beyond structured fields is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is front-loaded and efficient. The trailing "Returns: The profile." earns nothing, since an output schema already exists and the statement conveys no information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full annotation coverage, a documented parameter, and an output schema, the definition covers the essentials. Minor gaps (not-found/private-author behavior) are tolerable at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single `author` parameter is documented with concrete formats (user ID, handle with or without @, profile URL). The description adds nothing on top of that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Get an author's public profile") that an agent can clearly distinguish from siblings like list_author_models or get_model. It does not explicitly name those siblings, but the resource boundary is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus list_author_models or search_models, no prerequisites, and no exclusions. The agent must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_modelB
Read-onlyIdempotent

Get a model's full card: Markdown description, tags, category, license, print parameters, images, remixes.

Returns:
    The model details.
NameRequiredDescriptionDefault
modelYesModel ID ("3161") or model page URL

Output Schema

NameRequiredDescription
idYes
urlYes
nameYes
nsfwYes
tagsYes
likesYes
makesYesNumber of user-posted prints of the model
priceYesPurchase price in USD for paid models
viewsYes
authorYes
imagesYes
ratingYesAverage rating, 0-5
is_freeYesFree to download without purchase or a club membership
licenseYes
pdf_urlYes
printerYesPrinter the author used
ratingsYesNumber of ratings
summaryYes
categoryYes
commentsYes
remix_ofYes
club_onlyYesAvailable to Printables Club members only
downloadsYes
materialsYes
publishedYesPublication timestamp, ISO 8601
authorshipYes"original", "remix" or "reupload"
descriptionYesFull description as Markdown
weight_gramsYesFilament weight
multi_materialYes
first_publishedYes
print_time_minutesYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety and idempotency profile is covered. The description adds the useful fact that this is the "full card" surface (as opposed to a summary), but says nothing about failure behavior for an unknown ID, URL-vs-ID resolution, or rate limits. The trailing "Returns: The model details." line is vacuous rather than informative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is dense and well front-loaded with real content. However, the "Returns: The model details." stanza is pure filler that repeats the first sentence's premise and occupies roughly a third of the text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full schema coverage on the one parameter, the description only needs to characterize scope, which it does by naming the card's constituent parts. It is nearly complete; the main omission is any hint about behavior when the supplied ID or URL does not resolve.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single "model" parameter is already documented as an ID ("3161") or model page URL. The description adds no additional meaning about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ("Get a model's full card") and enumerates the payload it returns: description, tags, category, license, print parameters, images, remixes. That enumeration implicitly separates it from list-oriented siblings like search_models and list_model_files, but no sibling is named explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus search_models, list_author_models, or list_model_files, and no note on prerequisites such as needing a valid ID first. The only implied usage comes from the schema's single required "model" parameter; the description text itself offers no routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_author_modelsB
Read-onlyIdempotent

List models published by an author, page by page.

Returns:
    One page of the author's models and the cursor for the next one.
NameRequiredDescriptionDefault
limitNo
authorYesUser ID ("16"), handle ("Prusa3D" or "@Prusa3D") or profile URL
cursorNo`next_cursor` from the previous page
orderingNonewest

Output Schema

NameRequiredDescription
itemsYes
next_cursorYesPass as `cursor` to fetch the next page; null on the last page

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds one useful behavioral fact beyond that: results are paginated and each response carries a next-page cursor. It does not mention ordering effects, result limits, or what an empty page means, so 3 is appropriate rather than higher.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded and the return shape second. The "Returns" block is somewhat redundant given an output schema exists, but it costs little and remains well ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, idempotent paged-list tool with a full output schema, the definition covers what the tool returns at a level the output schema can expand on. The missing piece is the relationship to search_models and any guidance on ordering semantics, which keeps it below 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: author formats and cursor provenance are documented in the schema, while limit and ordering have no description at all. The tool description adds no parameter information whatsoever, so it fails to compensate for the undocumented half — notably the six enum ordering modes and the 1-100 limit bounds are left unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List models published by an author") and adds the paging scope, which clearly separates it from get_model or list_model_files. It does not, however, name or differentiate itself from the closest sibling, search_models, so an agent must infer that this is the browse-by-author path rather than the query path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Page by page" hints at the pagination workflow, but there is no statement of when to choose this tool over search_models or get_author, and no prerequisites or exclusions. The agent is left to infer usage entirely from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_categoriesA
Read-onlyIdempotent

List all model categories with their full paths; the IDs feed search_models(category_id=...).

Returns:
    All categories.
NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
categoriesYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered. The description adds useful non-annotated context: the result is the complete category set ('All categories'), returned with full paths, which tells the agent it is a full enumeration rather than a paginated or filtered view.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core sentence is front-loaded and dense with useful information. The trailing 'Returns: All categories.' largely restates what was already said in 'List all model categories', a minor redundancy that keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-argument enumeration tool with an output schema, annotations covering safety, and an explicit pointer to its downstream use, nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema needs no explanation; baseline applies. The mention of category_id refers to the sibling's parameter, not this tool's, so it adds routing value but no parameter semantics here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all model categories') plus the payload detail ('with their full paths'), which no sibling offers. It also names the downstream consumer, search_models(category_id=...), so the agent can place it relative to the sibling set immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete use case: call this first when you need a category_id to pass to search_models. That's a real when-to-use signal tied to a named sibling. It stops short of explicit exclusions (e.g., when list_licenses or get_model is the right call instead), so not a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_licensesA
Read-onlyIdempotent

List the licenses models are published under; the IDs feed search_models(license_ids=...).

Returns:
    All licenses.
NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
licensesYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered and the description carries a lighter burden. 'Returns: All licenses' usefully signals an unfiltered, unpaginated full enumeration, but nothing is said about ordering, caching, or whether the catalog is stable across calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines, front-loaded with the purpose and the downstream consumer of the returned IDs. The 'Returns: All licenses' line is terse and adds the completeness signal rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A zero-parameter list tool with an output schema and full annotation coverage needs very little prose, and this description delivers the essentials plus the search_models linkage. Minor gap: it does not state that the result set is small/complete enough to use without further pagination calls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case per the rubric; the description correctly implies a no-argument enumeration. The only added meaning ('All licenses') reinforces that no filter arguments exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource ('List the licenses models are published under') with a clear scope statement, and it explicitly ties itself to the sibling search_models by naming the license_ids parameter it feeds. An agent can distinguish this from list_categories or list_author_models without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The pointer that IDs feed `search_models(license_ids=...)` gives an explicit downstream workflow, which is real usage guidance rather than a restatement of the name. It stops short of stating when not to call it (e.g. that no filtering or pagination is offered), so it is clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_model_filesA
Read-onlyIdempotent

List every downloadable file of a model with sizes and, for G-code, printer/material/slicing parameters.

Use `get_download_links` to obtain the actual URLs.

Returns:
    All files of the model.
NameRequiredDescriptionDefault
modelYesModel ID ("3161") or model page URL

Output Schema

NameRequiredDescription
filesYes
model_idYes
model_urlYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and reproducibility are covered. The description adds which attributes accompany each file (sizes, G-code metadata), which is useful, but the closing "Returns: All files of the model" is vague and duplicates both the opening sentence and the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core capability and the URL alternative are front-loaded in two short sentences. The trailing "Returns:" block restates the first sentence and the output schema, so it is mild dead weight rather than a structural flaw.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full output schema, complete annotations, and a fully documented single parameter, the description only needs to convey scope and sibling routing, which it does. The G-code metadata note is a genuine value-add not visible from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and there is a single required parameter whose schema description already gives accepted forms ("Model ID (\"3161\") or model page URL"). The description adds nothing about the parameter, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List every downloadable file of a model") and adds the distinguishing payload details: file sizes and, for G-code, printer/material/slicing parameters. This separates it cleanly from get_download_links and from the model-listing siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the alternative and the condition that selects it: use `get_download_links` to obtain the actual URLs. An agent knows this tool enumerates files and does not resolve download URLs, which is the key routing decision here.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_modelsC
Read-onlyIdempotent

Search Printables models by text with optional filters and pagination.

Returns:
    The total match count and one page of model summaries.
NameRequiredDescriptionDefault
limitNo
priceNopaid includes club-only modelsall
queryYesSearch text; empty string lists everything
offsetNoSkip this many results (pagination)
orderingNobest_match
has_makesNoOnly models with user-posted prints
category_idNoCategory ID from `list_categories`
license_idsNoLicense IDs from `list_licenses`
published_within_daysNo

Output Schema

NameRequiredDescription
itemsYes
totalYesTotal number of matches (the API caps it at 10000)
offsetYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description's only added behavior is that results are paged and include a total count, which is somewhat useful but also available via the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines, purpose front-loaded, no filler. The 'Returns' block is slightly redundant given a declared output schema but is not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A 9-parameter search tool with two enums, a null-able tri-state filter and pagination needs guidance the description does not give — e.g. how limit/offset interact, what 'paid includes club-only models' implies, or when to set has_makes. Annotations and output schema cover part of the burden, but the description is thin for this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description says 'optional filters and pagination' without naming a single filter, ordering mode, or the limit cap. With schema coverage at 67% (ordering, limit and published_within_days carry no descriptions), the description does not compensate for the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search Printables models by text') plus the breadth of filtering, which separates it from get_model (single fetch) and list_author_models (author-scoped listing). No sibling is named explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to prefer this over list_author_models or list_model_files, and no prerequisites or exclusions. Only the implicit cue that a text query is required hints at usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.0
    • First observedget_author
    • First observedget_download_links
    • First observedget_model
    • First observedlist_author_models
    • First observedlist_categories
    • First observedlist_licenses
    • First observedlist_model_files
    • First observedsearch_models

TDQS

A3.7/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a clearly distinct resource and action: author model listing vs. author profile lookup, model search vs. model detail, file listing vs. download link retrieval, and category/license lookup. There is no meaningful overlap that would cause an agent to misselect a tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern such as list_author_models, search_models, get_model, list_model_files, and get_download_links. The convention is predictable and readable throughout.

Tool Count5/5

Eight tools is well-scoped for a read-only Printables browsing and download server. Each tool covers a distinct part of the model discovery and retrieval workflow without obvious redundancy.

Completeness4/5

The surface covers the core lifecycle of finding models, inspecting details, listing files, and obtaining download links, along with supporting category, license, and author lookups. Minor gaps exist, such as no dedicated author search or collection browsing, but these are not blocking for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    F
    maintenance
    Enables AI assistants to manage 3D printing inventory, filament spools, printers, projects, and print trackers through a self-hosted Print Vault instance.
    40
    AGPL 3.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Allows an AI assistant to search a local library of 3D-printable models, retrieve geometry metrics like dimensions, triangle counts, and watertightness, and draft marketplace listings.
    GPL 3.0