gpaul mcp MCP ravelry

A Model Context Protocol server that turns AI assistants into a knitting and crochet companion, with Ravelry as the backbone: pattern and yarn search with a photo carousel, your stash, queue and projects, exact calculators, and a row counter.

This project was inspired by my girlfriend, whose passion for knitting and crochet encouraged me to create this bridge between AI assistants and the Ravelry crafting community. Since she's not very tech-savvy and somewhat skeptical about AI, this serves as my way of connecting with her interests and showing how technology can enhance her crafting experience rather than replace it.

A hosted instance is running at:

https://ravelry-mcp.gonz-paul.dev/mcp

You don't need a Ravelry account or API key: add the URL to your AI assistant and start asking.

Claude (web, desktop and mobile): Settings → Connectors → Add custom connector, give it a name ("Ravelry") and paste the URL. Once added, it is available everywhere you use Claude.

ChatGPT: add the URL as a custom MCP connector (developer mode), with no authentication.

Claude Code

claude mcp add --transport http ravelry https://ravelry-mcp.gonz-paul.dev/mcp

VS Code (.vscode/mcp.json)

{
  "servers": {
    "ravelry": { "type": "http", "url": "https://ravelry-mcp.gonz-paul.dev/mcp" }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "ravelry": { "url": "https://ravelry-mcp.gonz-paul.dev/mcp" }
  }
}

New here? Everything it can do, organised by what you want to do, and how to set up a Claude project as your knitting & crochet guide (instructions to paste included).

Then try one of the example prompts, or the built-in starters: Find a pattern, Substitute a yarn, What can I make with this yarn? and Yarn shops near me.

The hosted server only reads public Ravelry data with this project's read-only API key (with Ravelry's permission), stores nothing about your conversations, and allows 60 requests per minute per user. Prefer to run your own? See Run it yourself.

To also let your assistant read your stash, queue, projects, favorites and library, add this URL instead:

https://ravelry-mcp.gonz-paul.dev/account/mcp

The first time, your assistant opens a page where you sign in with Ravelry, then confirm on a second page which app gets access. Reading is the default; changing your stash, queue and projects needs a second permission on the same page, and the assistant confirms each change with you first. You can revoke access at any time from your Ravelry account's app settings.

Then you can ask things like:

• "What should I make next?" (it checks which queued patterns your stash already covers)
• "What can I make with the DK yarn in my stash?"
• "Look at my projects and tell me what kind of maker I am." (a crafting profile your assistant can remember)

What the server stores: your Ravelry username and its Ravelry sign-in tokens, encrypted, so it can keep your connection working, and the row counters you create (encrypted, deleted when you remove them). Nothing else about you or your conversations.

The assistant uses these instead of doing knitting arithmetic in its head, so the numbers are right and it can focus on explaining.

Starters: Read me this row, Chart ↔ written instructions, Find a pattern from a photo and Fix my knitting or crochet problem.

Plus three extra starters: What should I make next?, Use up my stash and Add yarn to my stash from a photo.

Changing anything needs one extra permission ("add, update and remove" on your stash, queue and projects), asked on the same consent page. Your assistant confirms before each change.

Ravelry itself does the yarn bookkeeping: when a project uses part of a stash entry, Ravelry keeps that amount aside and the rest stays free. So the assistant works through projects:

1. Start: "Let's start Musselburgh with my teal Rios": the project is created and the yarn is set aside.
2. Work: "I'm at row 42 of the brim, used about one skein": a dated line goes into the project's private notes (your progress log) and the yarn used is updated. Next time, "where was I?" reads that log.
3. Finish or frog: finished projects keep their yarn and the leftovers stay in your stash (yarn with nothing left becomes "used up"); frogged projects give the yarn back.

That way "what can I make with my stash?" and "what can I start from my queue?" only count yarn that is really free.

In apps that support MCP Apps (Claude, ChatGPT…), two kinds of results show up as interactive widgets; everything else stays plain text:

• Pattern carousel (search_patterns, discover_patterns_for_me, find_patterns_for_my_stash): swipeable cards with the pattern photo (tap it to open Ravelry), difficulty, yarn weight, yardage, rating and price. Tap 👍 or 👎 on each one; your picks are shared with the assistant as you go, and Find more like my 👍 asks it to dig deeper in that style. Each card also has Similar, Details and + Queue.
• Row counter (get_row_counter), for a Ravelry project or anything you name: big − / + buttons that respond instantly (saved in the background), keyboard support (↑ / ↓ / space), several counters per project, a target and the position in the pattern repeat, and Save to Ravelry log.

Only needed if you don't want to use the hosted instance. Requires Node.js 22 or later and your own Ravelry API key.

The server uses Ravelry's read-only basic-auth API keys, not your Ravelry login:

1. Sign in at https://www.ravelry.com/pro/developer (a free Pro account is created if you don't have one).
2. Create an app and choose basic auth with read-only access.
3. Copy the generated username and password.

npm install
npm run pack:mcpb

Then double-click the generated ravelry-mcp.mcpb (or drag it onto Claude Desktop's Settings → Extensions page). Claude Desktop asks for the API username and password and stores the password securely.

git clone https://github.com/gpaul-mcp/MCP_ravelry.git
cd MCP_ravelry
npm install
npm run build

Claude Code

claude mcp add ravelry -e RAVELRY_USERNAME=your-api-username -e RAVELRY_PASSWORD=your-api-password -- node /absolute/path/to/MCP_ravelry/dist/index.js

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ravelry": {
      "command": "node",
      "args": ["/absolute/path/to/MCP_ravelry/dist/index.js"],
      "env": {
        "RAVELRY_USERNAME": "your-api-username",
        "RAVELRY_PASSWORD": "your-api-password"
      }
    }
  }
}

VS Code (.vscode/mcp.json, prompts for the password instead of storing it in the file)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ravelry-password",
      "description": "Ravelry API password",
      "password": true
    }
  ],
  "servers": {
    "ravelry": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/MCP_ravelry/dist/index.js"],
      "env": {
        "RAVELRY_USERNAME": "your-api-username",
        "RAVELRY_PASSWORD": "${input:ravelry-password}"
      }
    }
  }
}

All configuration comes from environment variables. For local development you can put them in a .env file (see .env.example); it is git-ignored.

MCP_TRANSPORT=http npm start serves Streamable HTTP at http://127.0.0.1:3000/mcp, plus GET /health and a short landing page at / that shows the connector URL. Host and Origin headers must be localhost or one of MCP_ALLOWED_HOSTS (protection against DNS rebinding).

To host your own instance that people add to Claude or ChatGPT by URL (like the hosted one above), follow Self-hosting with Cloudflare Tunnel: a Docker Compose setup that runs it on your own machine for free.

/account/mcp is an OAuth-protected MCP endpoint, following the MCP authorization spec:

1. An unauthenticated request gets 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource/account/mcp, which names this server as the authorization server.
2. The client discovers /.well-known/oauth-authorization-server, registers itself (dynamic client registration) and starts an authorization-code flow with PKCE (required).
3. The server (oidc-provider) sends the user to Ravelry's OAuth to sign in, then shows its own consent page naming the client. Each new client must be approved, so another app can't silently reuse someone's Ravelry sign-in.
4. The client receives an access token (1 hour) and refresh token, scoped to /account/mcp (RFC 8707). Ravelry's own tokens never leave the server; they are refreshed as needed.

Everything is stored in SQLite under DATA_DIR: lookup keys are hashed and every record (including Ravelry tokens) is encrypted with a key derived from AUTH_SECRET.

npm run dev        # run from source with auto-restart (Node runs the TypeScript directly)
npm run inspect    # build and open the MCP Inspector against the server
npm run check      # typecheck + lint + tests
npm run smoke      # after `npm run build`: live end-to-end test against the real Ravelry API

A Husky pre-commit hook runs lint-staged, the typecheck and the tests. CI runs the same checks on Node 22 and 24.

src/
├── index.ts                    # Entry point: config, transport (stdio or HTTP), shutdown
├── server.ts                   # createServer() factory: server info, instructions, tools
├── config.ts                   # Environment variable parsing and validation (zod)
├── http.ts                     # Streamable HTTP: host checks, URL secret, rate limit, /health, landing page
├── rate-limit.ts               # Per-client request limiter
├── prompts.ts                  # Conversation starters (MCP prompts)
├── auth/                       # "Sign in with Ravelry": OAuth server, consent page, storage
│   ├── server.ts               # oidc-provider setup, Ravelry login step, consent, token checks
│   ├── ravelry-oauth.ts        # Ravelry's OAuth 2.0 endpoints
│   ├── accounts.ts             # Signed-in accounts and Ravelry token refresh
│   ├── adapter.ts / db.ts      # Encrypted SQLite storage
│   └── crypto.ts / pages.ts    # Key derivation, encryption, HTML pages
├── account/                    # Personal tools for signed-in users
│   ├── lists.ts                # get_my_stash, get_my_queue, get_my_projects, ...
│   ├── insights.ts             # find_patterns_for_my_stash, pick_from_my_queue, profile
│   ├── stash.ts                # Stash normalization (yards per weight)
│   └── setup.ts                # Wires sign-in and the per-user server
├── ravelry/
│   ├── client.ts               # Ravelry API client (fetch, timeouts, cancellation, errors)
│   ├── types.ts                # Ravelry API response types
│   └── vocabulary.ts           # Verified filter values and category resolution
└── tools/
    ├── search-patterns.ts      # search_patterns tool
    ├── get-pattern-details.ts  # get_pattern_details tool
    ├── yarns.ts                # search_yarns and get_yarn_details tools
    ├── find-yarns-for-pattern.ts # find_yarns_for_pattern tool
    ├── find-yarn-shops.ts      # find_yarn_shops tool
    └── format.ts               # Shared formatting helpers
test/                           # Vitest tests (in-process MCP client, mocked Ravelry API)
scripts/
├── smoke.ts                    # Live end-to-end check over stdio
└── pack-mcpb.ts                # MCP Bundle packaging
manifest.json                   # MCP Bundle manifest

1. Create src/tools/<name>.ts exporting register<Name>(server, ravelry) that calls server.registerTool() with a title, a description written for the model, a zod inputSchema (use .describe() on every field), an outputSchema, and annotations.
2. Register it in src/server.ts and list it in manifest.json.
3. Add a test in test/server.test.ts.

MIT, see LICENSE.

Ravelry MCP Server turns AI assistants like Claude and ChatGPT into a knitting and crochet companion, with Ravelry as the backbone. It searches patterns and yarns, reads and updates a maker's own stash, queue and projects through "Sign in with Ravelry", does every crafting calculation exactly, and shows interactive widgets in the chat: a photo carousel of patterns and a row counter. A hosted instance runs at ravelry-mcp.gonz-paul.dev.

• Pattern search by technique, yarn weight, yardage, difficulty and fit, shown as a photo carousel with 👍/👎 feedback the assistant uses to refine the next search
• Personal Ravelry data through OAuth: stash, queue, projects, favorites, library and needles, with project tracking that keeps the stash accurate
• Exact calculators the assistant calls instead of guessing: gauge adjustment, even increases and decreases, yarn quantities, grams ↔ meters, and a stitch counter that checks written pattern rows
• Planning from the user's own data: finish-date predictions from their pace, shopping lists after the stash, queue and stash check-ups, pattern suggestions to learn new skills
• Interactive row counter widget with instant taps saved server-side, for Ravelry projects or anything else
• Metric or imperial preference, US/UK terminology, needle size and yarn weight conversions

• TypeScript
• Node.js
• Model Context Protocol (MCP) TypeScript SDK v2
• MCP Apps (interactive widgets)
• OAuth 2.1 (oidc-provider, PKCE, dynamic client registration)
• SQLite with AES-256-GCM encryption
• Zod
• Vite
• Vitest
• Docker and Cloudflare Tunnel
• Ravelry API