TimeLib MCP — AI agent for your Medusa store

An MCP server that lets an AI agent (Claude Desktop, Claude Code, or any MCP client) add and manage products — plus inventory, collections/categories, orders and customers — in your TimeLib Medusa v2 store via the Admin API.

You just chat, e.g.:

"Add a product called Chrono Field Watch, a draft, with S/M/L bands at $180, 20 in stock each, in the Watches collection."

and the agent creates it.

---

What the agent can do

Area	Tools
Orientation	get_store_context (regions, currencies, sales channels, locations)
Products	list_products, get_product, create_product, update_product, delete_product
Variants	create_variant, update_variant, delete_variant
Inventory	list_inventory_items, set_inventory_level
Catalog	list_collections, create_collection, list_categories, create_category, list_product_tags, list_product_types
Orders / Customers	list_orders, get_order, list_customers
Anything else	medusa_admin_request (raw Admin API escape hatch)

---

Setup (one time)

1. Install

cd timelib-mcp
npm install

2. Configure credentials

cp .env.example .env

Open .env. MEDUSA_BACKEND_URL is already filled in. You need admin credentials. Two options:

Option A — Secret API key (recommended: non-expiring, revocable, no password stored). Temporarily put your Medusa admin email + password in .env, then:

npm run create-key

Copy the printed token into MEDUSA_ADMIN_API_KEY in .env, then delete the email/password lines.

Option B — Email + password. Just set MEDUSA_ADMIN_EMAIL and MEDUSA_ADMIN_PASSWORD in .env and leave MEDUSA_ADMIN_API_KEY empty. The server logs in and refreshes the token automatically.

3. Test the connection

npm run smoke

You should see ✅ Auth OK and a few product titles.

---

Connect it to Claude

Claude Code (CLI)

claude mcp add timelib -- node "C:\Users\dashi\Desktop\Projects\TimeLib\timelib-mcp\src\index.mjs"

(Credentials are read from timelib-mcp/.env, so you don't need to pass them on the command line. To pass them explicitly instead, add -e MEDUSA_BACKEND_URL=... -e MEDUSA_ADMIN_API_KEY=... before the --.)

Verify with claude mcp list, then in a session ask: "What tools does timelib expose?"

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "timelib": {
      "command": "node",
      "args": ["C:\\Users\\dashi\\Desktop\\Projects\\TimeLib\\timelib-mcp\\src\\index.mjs"]
    }
  }
}

Restart Claude Desktop. The 🔌 icon should show the timelib tools.

---

Hosting the server (remote / always-on)

The server has two entrypoints that share the same tools:

Entrypoint	Command	Use
Local (stdio)	node src/index.mjs	Claude launches it on your machine
Hosted (HTTP)	node src/http-server.mjs	Runs as a web service; clients connect over HTTPS

The hosted server exposes MCP at POST /mcp and is protected by a static bearer token (MCP_AUTH_TOKEN). It refuses to start without one.

Deploy to Railway (new service in the TimeLib project)

1. Push timelib-mcp/ to a Git repo (GitHub).
2. In your existing TimeLib Railway project → New → GitHub Repo → pick this repo (set the root directory to timelib-mcp if it lives in a monorepo).
3. Railway reads railway.json and runs node src/http-server.mjs.
4. Add these Variables in the service:
   • MEDUSA_BACKEND_URL = https://timelib-production.up.railway.app
   • MEDUSA_ADMIN_API_KEY or MEDUSA_ADMIN_EMAIL + MEDUSA_ADMIN_PASSWORD
   • MCP_AUTH_TOKEN = a long random secret (see below)
   • (PORT is injected by Railway automatically.)
5. Under Settings → Networking, generate a public domain. You'll get a URL like https://timelib-mcp-production.up.railway.app. Your MCP endpoint is that URL + /mcp.

Generate a token:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Sanity-check the deploy:

curl https://YOUR-MCP-DOMAIN.up.railway.app/         # -> {"name":"timelib-mcp","status":"ok",...}

Connect clients to the hosted server

Claude Code (CLI) — native HTTP transport with a header:

claude mcp add --transport http timelib-remote https://YOUR-MCP-DOMAIN.up.railway.app/mcp \
  --header "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"

Claude Desktop — use the mcp-remote bridge (no native header field in the UI):

{
  "mcpServers": {
    "timelib-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOUR-MCP-DOMAIN.up.railway.app/mcp",
        "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
      ]
    }
  }
}

Claude.ai web / mobile — uses OAuth (see next section). No token to paste; you approve access with your owner password in the browser.

---

OAuth for claude.ai web / mobile

claude.ai custom connectors authenticate via OAuth, not a static token. The hosted server implements a full OAuth 2.1 flow (metadata discovery, dynamic client registration, authorize + token endpoints, PKCE, refresh tokens). It's stateless — client registrations and tokens are signed JWTs, so it survives Railway redeploys with no database. Access is gated by a single owner password.

Enable it

Add two more variables to the Railway service and redeploy:

OWNER_PASSWORD   = <a password you'll type to approve access>
OAUTH_JWT_SECRET = <64+ random hex chars: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))">

PUBLIC_URL is auto-detected from Railway's RAILWAY_PUBLIC_DOMAIN. The static MCP_AUTH_TOKEN keeps working for Claude Code/Desktop at the same time.

Connect claude.ai

1. claude.ai → Settings → Connectors → Add custom connector.
2. URL: https://YOUR-MCP-DOMAIN.up.railway.app/mcp
3. Claude discovers the OAuth endpoints and opens a login page → enter your OWNER_PASSWORD → Authorize.
4. The timelib tools appear in claude.ai (web and mobile).

Health check shows which modes are active:

curl https://YOUR-MCP-DOMAIN.up.railway.app/    # -> "auth":{"static_token":true,"oauth":true}

---

Notes & safety

• Prices are in major currency units in Medusa v2 (e.g. 25 = $25.00, not cents).
• New products default to draft. Ask the agent to set status: "published" (or use update_product) to make them live.
• Destructive actions (delete_product, deletes via medusa_admin_request) are permanent — the agent is instructed to confirm with you first, but review before approving.
• The secret API key has full admin access. Keep .env out of version control (already in .gitignore) and revoke the key in the Medusa admin if it leaks.
• Product images are passed as public URLs. To upload local files first, use the Medusa admin UI or extend the server with the /admin/uploads endpoint via medusa_admin_request.
• Hosted server = full admin access behind one token. Anyone with the MCP_AUTH_TOKEN and the URL can manage your store. Use a long random token, store it only in Railway variables + your client config, and rotate it (change the variable, redeploy) if it leaks.
• OAuth secrets: OWNER_PASSWORD is your login to approve claude.ai access — make it strong. Changing OAUTH_JWT_SECRET (or a redeploy that loses it) invalidates all issued tokens and registered connectors, so clients must reconnect. Keep it stable in Railway variables.