inkeedecoder-mcp
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., "@inkeedecoder-mcp Look up the ingredients in CeraVe Moisturizing Cream"
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.
@knorby/inkeedecoder-mcp
An MCP (Model Context Protocol) server for INKEEDecoder — the community-run database of cosmetic products and ingredients, formerly known as INCIDecoder.
It wraps @knorby/inkeedecoder-client
and exposes it to MCP hosts: search for products and ingredients, read a
product's ingredient list, look up what an ingredient does and how it is rated,
and follow the links between them. Runs locally over stdio, needs no API key,
and is installable with npx.
Not affiliated with INKEEDecoder. This project reads publicly available pages the same way a browser does. Data is user-submitted and may be incomplete or out of date; it is not medical advice.
Tools
Tool | What it does |
| Search products and ingredients by name. Returns both tabs, or one tab with |
| Advanced product search: filter by ingredients a product must contain ( |
| A product page: brand, description, ingredient list, hashtags, plus optional sections you opt into. |
| An ingredient page: what it does, INKEEDecoder's rating, irritancy/comedogenicity, and optional CosIng data, long-form writeup, and references. |
| The reverse of a product page: which products contain a given ingredient. |
| A brand and its catalogue. |
| An ingredient function (for example |
| Connectivity and configuration check. Sends no request to the site. |
Every tool is read-only and idempotent. Every list is paginated: a response
tells you whether another page exists, and you ask for it with page. Results
are bounded — when one has to be shortened, the text says so.
Verbose sections (long_descriptions, skim_table, tooltips, details,
proof) are off by default because a single product's ingredient writeups can
fill a context window on their own.
Related MCP server: opencosmetics
Installing
With an MCP host
{
"mcpServers": {
"inkeedecoder": {
"command": "npx",
"args": ["-y", "@knorby/inkeedecoder-mcp"]
}
}
}From a local checkout, point at the built entrypoint instead:
{
"mcpServers": {
"inkeedecoder": {
"command": "node",
"args": ["/absolute/path/to/inkeedecoder-mcp/dist/index.js"]
}
}
}Config file locations vary by host: claude_desktop_config.json,
.cursor/mcp.json, .vscode/mcp.json, or claude mcp add on the CLI. There
is no API key to configure — the server reads public pages.
One-click in Claude Desktop
Every release ships an MCPB bundle —
inkeedecoder-mcp-<version>.mcpb — attached to its
GitHub Releases page.
Download it and open it with Claude Desktop (macOS or Windows) to install
with a single click.
Configuration
Every variable is optional. The defaults read inkeedecoder.com politely.
Variable | Default | Purpose |
|
| Site to read. Point it at a mirror or a locally archived copy. |
|
| Minimum spacing between requests, across tool calls. Values below the default apply only to mirrors — reads of inkeedecoder.com itself keep at least the default. |
|
| Abandon a request that takes longer than this. |
Pass them through the host's env block. The server never reads a .env file.
Links and identifiers
Every id argument accepts any of three shapes:
a slug —
squalane,the-ordinary-retinol-1-in-squalane(the last segment of the page URL)a site path —
/ingredients/squalanea URL —
https://inkeedecoder.com/ingredients/squalane
URLs from incidecoder.com work too. INCIDecoder renamed itself to INKEEDecoder after a trademark dispute with PCPC, the body that owns the INCI nomenclature (see inkeedecoder.com/new-name); it is the same site and the same database, and the old URLs redirect. This server accepts both hosts, keeps only the path, and fetches it from the configured base URL — so a stale link pasted from an old chat transcript still resolves, and the old domain is never contacted.
Links from any other host are rejected with an explanation, and passing an ingredient link to the product tool (or the reverse) returns an error naming the tool you wanted rather than mis-parsing the page.
Etiquette
The site is a volunteer-run database that permits the paths this server reads
(see its robots.txt) and asks that automated traffic stay light.
Requests are spaced by
INKEEDECODER_REQUEST_INTERVAL_MS— across separate tool calls, not just within one — and reads of inkeedecoder.com keep at least the default interval. Requests time out (INKEEDECODER_TIMEOUT_MS, 30 s by default) rather than piling up.Summarize rather than republishing the site's prose, and cite page URLs.
Expect gaps: entries are user-submitted.
Prerequisites
Node.js 24+ (use nvm or fnm; this repo includes an
.nvmrc). The server itself runs on Node 22+; the Inspector needs 22.19+.npm (bundled with Node).
pre-commit —
pipx install pre-commitorbrew install pre-commit.gitleaks —
brew install gitleaks(secret scanner for pre-commit).Go toolchain —
brew install go(required once for the TruffleHog hook build).
Getting started
git clone https://github.com/knorby/inkeedecoder-mcp.git
cd inkeedecoder-mcp
nvm use # or: fnm use
npm install
npx husky # set up hooks (prepare is blocked by .npmrc ignore-scripts)
pre-commit install # file hygiene + secret scanning
pre-commit run --all-filesThe first pre-commit run installs hook environments and builds TruffleHog
from source (a few minutes). Later runs are cached and fast.
Development
Command | What it does |
| Build the server (tsup bundle + |
| Run the server from source with |
| Open the MCP Inspector web UI against the built server |
| Call |
| Inspector CLI smoke test against |
| Lint + formatting check with Biome (read-only) |
| Format with Biome (writes changes) |
| Lint + format in one pass (writes changes) |
| Type-check |
| Run tests once (Vitest) |
| Run tests in watch mode |
| Run tests with coverage reporting |
npm run inspect is the fastest loop — it launches the server, lists its
tools, and lets you call them with arguments in a browser.
Project structure
src/
index.ts # stdio entrypoint (`bin`) — serveStdio(createServer)
server.ts # createServer(): registers tools, resources, prompts
config.ts # lazy Zod-parsed environment config
constants.ts # defaults, accepted link hosts, version from package.json
lib/
client.ts # builds and caches the inkeedecoder-client from config
ids.ts # slug/path/URL -> site path (host + type validation)
schemas.ts # output schemas mirroring the client's types
errors.ts # error -> actionable tool message
format.ts # markdown rendering + response bounding
log.ts # stderr-only logging
tools/ # one file per tool
resources/ # resource registrations
prompts/ # prompt registrations
tests/
helpers.ts # in-process test client (createMcpHandler + Client)
fixtures/ # real pages captured from the site (test inputs)
tools.test.ts # integration tests through a real client
config.test.ts # environment contract (defaults, floor)
stdio.test.ts # spawns dist/index.js and calls tools over stdio
inspector.config.json # MCP Inspector server config
dist/ # build output (gitignored)
.github/workflows/ # CI + release workflows
docs/decisions/ # architecture decision records (ADRs)Writing tools
A tool is a name, a config, and an async handler:
server.registerTool(
"inkeedecoder_get_brand",
{
title: "Get a brand's products",
description: "Fetch a brand page and its catalogue, one page at a time. Read-only.",
inputSchema: z.object({
id: z.string().min(1).describe("Brand slug, /brands/ path, or URL."),
page: z.number().int().min(1).default(1).describe("1-based page number."),
}),
outputSchema: z.object({ name: z.string(), products: paginatedSchema(refSchema) }),
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
},
async ({ id, page }, ctx) => {
const resolved = resolveEntityId(id, "brands");
if (!resolved.ok) {
return { content: [{ type: "text", text: resolved.error }], isError: true };
}
const client = getClient();
if (!client.ok) {
return { content: [{ type: "text", text: client.error }], isError: true };
}
try {
const brand = await client.client.getBrand(resolved.path, {
page,
signal: ctx.mcpReq.signal, // cancellation from the host
});
const bounded = boundStructured(brand);
return {
content: [{ type: "text", text: applyCharacterLimit(render(brand)) }],
structuredContent: bounded.value,
};
} catch (error) {
return {
content: [{ type: "text", text: toUserMessage(error, "Brand lookup") }],
isError: true,
};
}
},
);Conventions this repo follows:
Naming —
inkeedecoder_{action}in snake_case, so tools from several servers don't collide in one host..describe()every field — the model reads these to decide what to pass. A test asserts this for every registered tool.Inputs snake_case; outputs camelCase — output field names match
@knorby/inkeedecoder-clientexactly, sostructuredContentis a faithful view of the library's result with no translation layer to drift.Annotations — set
readOnlyHint,destructiveHint,idempotentHint, andopenWorldHinton every tool.outputSchema+structuredContent— typed, parseable results alongside the text block.Errors are results, not throws — return
content: [...], isError: truewith text that says what to do next. A thrown error becomes an opaque protocol error the model can't recover from.Never write to stdout — it carries the JSON-RPC stream. Use
logInfo/logWarn/logErrorfromsrc/lib/log.ts(all stderr).Bound your responses — paginate, and run both halves of a result through
applyCharacterLimit(text) andboundStructured(structured content); the text tells the model when fields were shortened.Honor cancellation — pass
ctx.mcpReq.signalinto the client so a host cancelling a call stops the in-flight request.
Testing
Four layers, cheapest first:
In-process integration tests (
tests/tools.test.ts).createMcpHandlerexposes the server as a web-standardfetchhandler, so a realClientdrives it with no port and no protocol mocks.fetchis stubbed with real pages captured from the site (tests/fixtures/), so the client's parsers run against the markup the site actually serves:const harness = await createTestClient(); const result = await harness.client.callTool({ name: "inkeedecoder_get_ingredient", arguments: { id: "squalane" }, }); expect(result.structuredContent).toMatchObject({ ourTake: "goodie" });Assert on
structuredContent; failures resolve as results withisError: true. The same file covers link handling, response bounding, request spacing, timeouts, and cancellation.Configuration tests (
tests/config.test.ts). The environment contract: defaults, coercion, and the politeness floor for inkeedecoder.com.stdio spawn test (
tests/stdio.test.ts). Spawns the built binary viaStdioClientTransport— the only way to catch a missing shebang or a strayconsole.log. It skips itself whendist/is absent, so a bare checkout can still runnpm test.Inspector smoke test (
npm run test:smoke). Runsmcp-inspector --cli --config inspector.config.json --server local --method tools/listagainstdist/, in CI after the build.
Releases
Published to npm as @knorby/inkeedecoder-mcp from GitHub Actions with OIDC
trusted publishing — no npm tokens involved. A release is a version bump in a
PR (package.json + server.json + manifest.json, pinned equal by the test
suite); merging it publishes, tags, and attaches the .mcpb bundle to the
GitHub Release. See CONTRIBUTING.md for the details,
including the manual first publish.
Documentation
AGENTS.md— instructions and steering for AI coding agents.CONTRIBUTING.md— development workflow, commit conventions, publishing.docs/— design notes, architecture, and decision records.MCP TypeScript SDK v2 docs — the authoritative reference for the server API.
License
Apache-2.0 © Kali Norby (@knorby)
Available Tools
8 toolsinkeedecoder_get_brandGet a brand's productsARead-onlyIdempotent
Fetch a brand page from INKEEDecoder (formerly INCIDecoder) and its catalogue of products, one page at a time. Accepts a slug, a /brands/ path, or an inkeedecoder.com or incidecoder.com URL. Read-only.
Inputs: id (required), page. Returns: url, name, path, slug, +1 more
inkeedecoder_get_ingredientGet an ingredientARead-onlyIdempotent
Fetch a cosmetic ingredient page from INKEEDecoder (formerly INCIDecoder): what it does, INKEEDecoder's rating, irritancy and comedogenicity, and optional CosIng identifiers, long-form writeup, and references. Accepts a slug, an /ingredients/ path, or an inkeedecoder.com or incidecoder.com URL. The long writeup is off by default. Read-only.
Inputs: id (required), image, proof, cosing, +4 more. Returns: url, name, path, slug, +9 more
inkeedecoder_get_ingredient_functionGet an ingredient functionARead-onlyIdempotent
Fetch an ingredient-function page from INKEEDecoder (formerly INCIDecoder) — what the function means and which ingredients serve it (for example "emollient"). Accepts a slug, an /ingredient-functions/ path, or an inkeedecoder.com or incidecoder.com URL. Returns one page of ingredients at a time. Read-only.
Inputs: id (required), page. Returns: url, name, path, slug, +2 more
inkeedecoder_get_ingredient_productsGet products containing an ingredientARead-onlyIdempotent
List the cosmetic products on INKEEDecoder (formerly INCIDecoder) that contain a given ingredient — the reverse of a product page. Optionally include the products that declare the ingredient's percentage. Returns one page at a time. Read-only.
Inputs: id (required), page, include_known_amount. Returns: products, knownAmountProducts
inkeedecoder_get_productGet a productARead-onlyIdempotent
Fetch a cosmetic product page from INKEEDecoder (formerly INCIDecoder): brand, description, and full ingredient list, plus optional sections you opt into (grouped-by-function ingredients, irritancy/comedogenicity table, tooltips, long ingredient writeups). Accepts a slug, a /products/ path, or an inkeedecoder.com or incidecoder.com URL. Returns one page of data — verbose sections are off by default. Read-only.
Inputs: id (required), brand, dates, images, +8 more. Returns: url, name, path, slug, +11 more
inkeedecoder_pingPing the INKEEDecoder serverARead-onlyIdempotent
Check that the server is running and report which INKEEDecoder base URL it will read from. Sends no request to the site. Use it to verify configuration before calling lookup tools.
Inputs: message. Returns: ok, reply, server, baseUrl
inkeedecoder_searchSearch products and ingredientsARead-onlyIdempotent
Search INKEEDecoder (formerly INCIDecoder) for cosmetic products and ingredients by name. Returns names, slugs, and URLs — one page at a time. Pass a result's slug to inkeedecoder_get_product or inkeedecoder_get_ingredient for the full page. Read-only: it never modifies anything.
Inputs: query (required), tab, page. Returns: tab, query, results, products, +1 more
inkeedecoder_search_productsSearch products by ingredientARead-onlyIdempotent
Search INKEEDecoder for cosmetic products using the advanced filter: match a name and/or require and forbid specific ingredients. Use it for questions like "moisturizers with squalane and no fragrance". Returns one page of products — each response says whether another page is available. Read-only.
Inputs: page, query, exclude, include, +1 more. Returns: page, items, hasMore, nextPageUrl
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools map to a clearly distinct resource (product, ingredient, brand, ingredient-function) or action (ping, reverse lookup). The only real friction is between inkeedecoder_search and inkeedecoder_search_products, which both find products; the descriptions do distinguish name-only search from ingredient-filtered search, but an agent could plausibly pick the wrong one for a query like 'moisturizers with squalane'.
Every tool uses the same inkeedecoder_ prefix followed by a snake_case verb_noun form (get_product, get_brand, search_products, get_ingredient_products). The pattern is predictable and reads cleanly; ping is the only bare verb and is unambiguous.
Eight tools is well-scoped for a read-only cosmetic-database reader: one health check, two search entry points, four resource fetchers, and one reverse lookup. No tool feels redundant or padding.
Coverage is strong for the read-only domain: search, product, ingredient, brand, ingredient-function pages, and the ingredient-to-products reverse lookup all exist, with pagination noted. The main gap is that search only returns products and ingredients, so there is no direct way to discover brand slugs or list brands before calling inkeedecoder_get_brand; agents must guess or route through product pages.
Maintenance
Related MCP Connectors
Public K-beauty catalog, product search, and latest-offers tools with canonical product facts.
Read-only tools over an independently vetted catalog of non-toxic home and baby products.
Open Beauty Facts MCP — Open Beauty Facts API (free, no auth, keyless).
Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables checking cosmetic ingredient safety and multi-jurisdiction compliance across 12 regulatory bodies, backed by a comprehensive dataset of safety opinions and studies.1MIT
- FlicenseNot gradedqualityBmaintenanceEnables querying cosmetics ingredient data across EU, China, and US regulations, running 65-rule formula risk reviews, multi-region compliance checks, and retrieving synthetic biology company metadata via natural language.-
- FlicenseAqualityDmaintenanceProvides skincare product recommendations, ingredient conflict checks, and product lookups based on skin type and concerns.5-
- AlicenseNot gradedqualityBmaintenanceEnables searching YouTube Music and managing playlists through read and confirmation-gated write tools over STDIO. Supports identity checks, song search, playlist listing/retrieval, and previewed playlist creation, track addition, and exact track removal.MIT