{"_id":"@apimio/mcp","_rev":"2-dd45c565d6b660a0eb57d6b5bd313afb","name":"@apimio/mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@apimio/mcp","version":"1.0.0","keywords":["apimio","mcp","modelcontextprotocol","model-context-protocol","claude","pim","product-information-management","shopify","product-catalog","openapi"],"author":{"name":"Apimio"},"license":"MIT","_id":"@apimio/mcp@1.0.0","maintainers":[{"name":"zurehman","email":"zia@apimio.com"}],"homepage":"https://app.apimio.com/developers","bugs":{"url":"https://apimio.com/contact"},"bin":{"apimio-mcp":"index.mjs"},"dist":{"shasum":"b05616599e969b5f4bc6f2afc35bf83653cef491","tarball":"https://registry.npmjs.org/@apimio/mcp/-/mcp-1.0.0.tgz","fileCount":4,"integrity":"sha512-sMEeWT6i+AsYFulfqHioalY78NG5cUxnf0hGIZazKQW/Jyt+gscUX2L7f1ZzxtByzYGe0OJ6UwCE+BdrhKannA==","signatures":[{"sig":"MEUCIB34+qGiG1/wxs4O7LbQuK5cZLZtMRIHZDn8SrITov1zAiEAwQJklR4EVg7Y9e8N4EROLtHyafKwQvthjwZvoihMAEs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12160},"type":"module","engines":{"node":">=18"},"_npmUser":{"name":"zurehman","email":"zia@apimio.com"},"_npmVersion":"10.9.2","description":"Model Context Protocol server for the Apimio Public API — gives AI tools (Claude Code, Cursor, etc.) typed access to your product catalog.","directories":{},"_nodeVersion":"22.17.0","dependencies":{"yaml":"^2.5.1","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.0_1786062002704_0.46517457733237944","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@apimio/mcp","version":"1.0.1","description":"Model Context Protocol server for the Apimio Public API — gives AI tools (Claude Code, Cursor, etc.) typed access to your product catalog.","type":"module","bin":{"apimio-mcp":"index.mjs"},"engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","yaml":"^2.5.1"},"keywords":["apimio","mcp","modelcontextprotocol","model-context-protocol","claude","pim","product-information-management","shopify","product-catalog","openapi"],"homepage":"https://app.apimio.com/developers","bugs":{"url":"https://apimio.com/contact"},"author":{"name":"Apimio"},"license":"MIT","publishConfig":{"access":"public"},"_id":"@apimio/mcp@1.0.1","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-VhiECNVSqvDUUY82MsHpPO4mBJ3QXnLIarWKyHlOKxBPd/KUe/8PvM1sl1OTnwAs/6tDfL6WaN96uWlPOPKq9w==","shasum":"39e336e562537b3f7d2994c8d4554962b2c8523a","tarball":"https://registry.npmjs.org/@apimio/mcp/-/mcp-1.0.1.tgz","fileCount":4,"unpackedSize":14669,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD257eebLlIAdhyK8bed5ofxA2aK1HwKA8jfqcfZktUNwIgZYX62s0jPnIrKFhCOCtJ0No2MyEevlkJt8gyiT1nfSM="}]},"_npmUser":{"name":"zurehman","email":"zia@apimio.com"},"directories":{},"maintainers":[{"name":"zurehman","email":"zia@apimio.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_1.0.1_1786063539130_0.515819462874646"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T00:20:02.494Z","modified":"2026-08-07T00:45:39.436Z","1.0.0":"2026-08-07T00:20:02.862Z","1.0.1":"2026-08-07T00:45:39.256Z"},"bugs":{"url":"https://apimio.com/contact"},"author":{"name":"Apimio"},"license":"MIT","homepage":"https://app.apimio.com/developers","keywords":["apimio","mcp","modelcontextprotocol","model-context-protocol","claude","pim","product-information-management","shopify","product-catalog","openapi"],"description":"Model Context Protocol server for the Apimio Public API — gives AI tools (Claude Code, Cursor, etc.) typed access to your product catalog.","maintainers":[{"name":"zurehman","email":"zia@apimio.com"}],"readme":"# @apimio/mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the\n**Apimio Public API**. It loads Apimio's live OpenAPI spec and exposes one tool\nper endpoint, so AI tools (Claude Code, Cursor, Claude Desktop, …) can read and\nmanage your product catalog directly. Your API key stays on your machine.\n\n## Before you start\n\nYou need all three of these, or you won't be able to generate a key:\n\n1. **Node 18+** — `npx` handles the install itself.\n2. **API access on your organization.** Available on the **Advanced** plan and\n   above, or enabled for you by an Apimio admin. If **Settings → API & Tokens**\n   shows a *\"Request API access\"* button instead of a list of keys, click it —\n   an admin has to approve before you can continue.\n3. **The \"Manage API Keys\" permission** (Owner or Admin). Without it that page\n   tells you to ask an Owner or Admin to generate a key for you.\n\n## Setup\n\n1. In Apimio, go to **Settings → API & Tokens** and click **Generate token**.\n   - Pick the **scopes** the key needs. If your assistant is only reading or\n     analysing the catalog, grant only the `:read` scopes — see\n     [Choosing scopes](#choosing-scopes).\n   - **Copy the key immediately.** It is shown once and never again.\n2. Add the server to your MCP client config:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"apimio\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@apimio/mcp\"],\n      \"env\": {\n        \"APIMIO_API_KEY\": \"apk_live_xxxxxxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\nThat's it — restart your client and ask it to \"list my Apimio products\" or\n\"create a product called Classic Tee\".\n\nNothing else is required. In particular there is **no organization id to\nconfigure**: each key is bound to one organization when it is created, and every\nrequest is scoped to that organization automatically.\n\n## Choosing scopes\n\nKeys are minted with granular scopes and they are enforced on every request — a\ncall outside a key's scopes returns `403 insufficient_scope`. The key-creation\nform grants **all** scopes by default, so narrow it deliberately:\n\n| Use case | Grant |\n|---|---|\n| Analysis, audits, reporting, \"what's missing?\" | the `:read` scopes only |\n| Enrichment, bulk edits, imports | `:read` + the `:write` scopes you need |\n\nWrite scopes are real write access: an assistant holding one can **delete**\nproducts, variants and categories. Prefer a read-only key and issue a separate\nwrite key only when you intend to make changes.\n\n## Configuration\n\n| Env var              | Default                                    | Purpose                                |\n|----------------------|--------------------------------------------|----------------------------------------|\n| `APIMIO_API_KEY`     | *(required)*                               | Bearer key.                            |\n| `APIMIO_BASE_URL`    | `https://app.apimio.com/api/v1`            | API base. Defaults to **production**.  |\n| `APIMIO_OPENAPI_URL` | `<origin of base>/developers/openapi.yaml` | Spec to generate tools from.           |\n\n**A key is valid on exactly one environment.** `APIMIO_BASE_URL` defaults to\nproduction, which is what a normal `apk_live_…` key needs. Only set it if your\nkey belongs elsewhere — for example an Apimio developer testing against\n`https://dev.apimio.com/api/v1`.\n\n## Tools\n\nTools are generated from the OpenAPI operations, so the tool set always matches\nthe current API. Today that is 47 tools covering products (including bulk\nimport), variants, per-market pricing, inventory, media, categories, brands,\nvendors, attributes, per-store overrides, locales, channels and webhooks — e.g.\n`listProducts`, `createProduct`, `bulkCreateProducts`, `setVariantPrices`,\n`setVariantInventory`, `createWebhookEndpoint`, `listWebhookDeliveries`.\n\n`ping` requires no scope, which makes it the quickest way to check that a key\nworks at all.\n\n## Troubleshooting\n\nThe tool list is built from the public spec, which loads **without** your key —\nso `loaded 47 tools` means the spec was reachable, not that your key is valid.\nIf every call then fails, start here:\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `401 unauthenticated` on every call | The key belongs to a different environment than `APIMIO_BASE_URL` | Point `APIMIO_BASE_URL` at the environment the key was created on |\n| `403 insufficient_scope` | The key lacks the scope for that endpoint | Generate a key with the needed scope |\n| `403 plan_not_entitled` | The organization no longer has API access | Check the plan, or ask an admin to enable it |\n| `Failed to load OpenAPI spec` | No network access to the API host, or a wrong `APIMIO_BASE_URL` | Confirm the host is reachable |\n| `APIMIO_BASE_URL is not a valid absolute URL` | Missing scheme, e.g. `app.apimio.com/api/v1` | Include `https://` |\n\n## Run locally\n\n```bash\nnpm install\nAPIMIO_API_KEY=apk_live_... node index.mjs\n```\n\nTo verify the spec loads and tools generate without starting a stdio session:\n\n```bash\nAPIMIO_SELFTEST=1 APIMIO_API_KEY=apk_live_... node index.mjs\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}