Punchneedle.ai MCP server
Commit Nov 12, 2026Converts images into punch needle patterns, estimates yarn requirements, and provides material compatibility guidance.
Also known as pyxlino/punchneedle-mcp, punchneedle-ai
- Stars
- 0
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Nov 12, 2026
- License
- —
What is Punchneedle.ai MCP?
Punchneedle.ai converts images into punch needle patterns, estimates yarn requirements, and provides material compatibility guidance. It exposes 7 tools, such as make_pattern_from_image, find_patterns, get_pattern.
Summary generated from the project's README
About Punchneedle.ai MCP server
Crafting custom punch needle designs from personal images is what this server enables for fiber artists. By providing an image address, a desired finished width, and a color limit, users can generate stitch-grid patterns that include specific yarn requirements for each color. The server connects via streamable HTTP and requires no account, sign-in, or API key for use in clients like Claude or ChatGPT.
Users can access a library of existing patterns by theme or difficulty level and resize designs while maintaining their original proportions. The toolset includes specialized calculators to estimate yarn needs based on dimensions, color shares, and needle loop height. It also provides material compatibility checks and detailed guidance on needles, fabrics like monk's cloth, and various yarn types to ensure all components work together correctly.
What you can do with it
- 1Generate custom patterns from photosConvert a public PNG, JPEG, or WebP image into a detailed stitch-grid pattern.
- 2Estimate necessary yarn amountsCalculate how much yarn is required for a specific design based on its size and color distribution.
- 3Verify material compatibilityCheck if a specific needle, fabric, and yarn type are suitable to use together.
- 4Browse themed pattern librariesFind existing punch needle patterns filtered by specific themes or skill levels.
Written from the project's README. Every use case is checked against a quote from it.
How to install Punchneedle.ai MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Punchneedle.ai MCP in Claude Code
$ claude mcp add --transport http punchneedle-ai https://punchneedle.ai/api/mcpInstall Punchneedle.ai MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"punchneedle-ai": {
"url": "https://punchneedle.ai/api/mcp"
}
}
}Install Punchneedle.ai MCP in VS Code
.vscode/mcp.json
{
"servers": {
"punchneedle-ai": {
"type": "http",
"url": "https://punchneedle.ai/api/mcp"
}
}
}Install Punchneedle.ai MCP in VS Code CLI
$ code --add-mcp '{"name":"punchneedle-ai","type":"http","url":"https://punchneedle.ai/api/mcp"}'Install Punchneedle.ai MCP in Codex
$ codex mcp add punchneedle-ai --url https://punchneedle.ai/api/mcpInstall Punchneedle.ai MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.punchneedle-ai] url = "https://punchneedle.ai/api/mcp"
Install Punchneedle.ai MCP in Gemini CLI
$ gemini mcp add -s user --transport http punchneedle-ai https://punchneedle.ai/api/mcpInstall Punchneedle.ai MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"punchneedle-ai": {
"url": "https://punchneedle.ai/api/mcp",
"type": "http"
}
}
}Punchneedle.ai MCP tools 7
Detected from the READMEmake_pattern_from_imagefind_patternsget_patterncalculate_yarnresize_patternmatch_materialsget_material_guide
| make_pattern_from_image | — | |
| find_patterns | — | |
| get_pattern | — | |
| calculate_yarn | — | |
| resize_pattern | — | |
| match_materials | — | |
| get_material_guide | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepyxlino/punchneedle-mcp is public and reachablegithub.com/pyxlino/punchneedle-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-12github.com/pyxlino/punchneedle-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 272 msPass
README
View on GitHubPunchneedle.ai MCP app
Make a punch needle pattern from your own image, or pick one from the library.
Give an image address, a finished width and a colour limit and get a stitch-grid pattern with the yarn each colour needs. Ask for patterns by theme, estimate yarn, resize a design or check that your needle, fabric and yarn work together. Answers come from the same pattern converter, calculators and guides as punchneedle.ai.
- Website: https://punchneedle.ai
- Documentation: https://punchneedle.ai/app
- Privacy: https://punchneedle.ai/privacy
- Terms: https://punchneedle.ai/terms
This repository documents the hosted connector. It does not contain the website or its code.
Connect
- Endpoint:
https://punchneedle.ai/api/mcp - Transport: Streamable HTTP
- Authentication: none (no account, sign-in or API key)
{ "mcpServers": { "punchneedle-ai": { "url": "https://punchneedle.ai/api/mcp" } } }
In ChatGPT, add it as a custom MCP server with no authentication. In Claude, open Customize, then Connectors, choose Add custom connector and enter the URL.
Tools
All tools are read-only.
| Tool | What it does |
|---|---|
make_pattern_from_image |
Converts a public PNG, JPEG or WebP image into a punch needle pattern with the website's pattern converter. |
find_patterns |
Lists the original punch needle patterns in the Punchneedle.ai library, filtered by theme and level. |
get_pattern |
Returns one library pattern with its size, colours, making steps, materials and the yarn each colour needs in a fine-wool kit and a rug-wool kit. |
calculate_yarn |
Estimates the yarn for a punch needle design from its size, the share of each colour and the needle and loop height, or from a measured swatch. |
resize_pattern |
Rescales a library pattern, or a design of a given size, to a new width or height with the proportions kept. |
match_materials |
Checks whether a punch needle, a fabric and a yarn work together, using the website's material guidance. |
get_material_guide |
Returns the website's guide to one punch needle material: needles, needle sizes, fabric, monk's cloth, yarn, floss, hoops or glue. |
Try asking
- "Show me punch needle flower patterns."
- "How much yarn do I need for a 30 by 20 cm punch needle piece that is 55% cream, 30% green and 15% gold?"
- "Will an Oxford regular punch needle work with rug yarn on monk's cloth?"
Report an issue
Open an issue in this repository or use the About page at https://punchneedle.ai/about.
License
The documentation files in this repository are MIT licensed (see LICENSE). The Punchneedle.ai website, its content, data and brand are not covered by this license.
Punchneedle.ai MCP questions
How do I add Punchneedle.ai MCP to Claude Code?
Run claude mcp add --transport http punchneedle-ai https://punchneedle.ai/api/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Punchneedle.ai MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Punchneedle.ai MCP provide?
It exposes 7 tools, including make_pattern_from_image, find_patterns, get_pattern, calculate_yarn, resize_pattern.
How can I create a pattern from an image?
You can provide an image address to convert a public PNG, JPEG, or WebP image into a stitch-grid pattern with yarn requirements.
Can I estimate how much yarn I need?
Yes, the server can estimate yarn based on design size, color shares, needle/loop height, or a measured swatch.
Does it check if my materials are compatible?
Yes, it can check if a specific needle, fabric, and yarn work together using the website's material guidance.