etsySellerAssistant

A local-first MCP assistant for Etsy sellers to review listings and draft improvements. It is designed for Codex Desktop over local STDIO, with read-only access first and explicit approval required for any future edits.

Current status

This repository contains the project foundation and a status-only MCP tool. It does not connect to Etsy, request credentials, read shop data, or change listings. The only available tool, get_setup_status, reports that Etsy access is not configured.

Related MCP server: Etsy Ops MCP

Supported platforms

• Windows 10/11 (x64)

• macOS (Apple Silicon or Intel)

• Node.js 24 or 26 LTS with npm 10 or later

Both Windows and macOS are supported development and runtime platforms. Use the path format and Node installation available on the computer where Codex Desktop runs.

How it works today

Codex Desktop starts the MCP server as a local process and exchanges messages over standard input/output (STDIO). The current server only reports setup status; there is no Etsy network connection.

flowchart LR
  seller[You] --> codex[Codex Desktop]
  codex <-->|MCP over local STDIO| server[etsySellerAssistant process]
  server --> status[get_setup_status]
  status --> result[Etsy access: not configured]
  server -. "No Etsy API calls in current release" .-> etsy[(Etsy Open API)]

First-time setup

1. Install prerequisites

Install Git and Node.js 24 or 26 LTS from a trusted source or version manager. The same terminal commands work in PowerShell, Command Prompt, and macOS Terminal:

git --version
node --version
npm --version

Confirm Node reports version 24.x or 26.x and npm reports version 10 or later. Codex Desktop needs to be able to start the same Node installation. If you install Node while Codex is open, restart Codex Desktop before configuring the server.

2. Clone the repository

Choose a folder where you keep development projects, then run:

git clone https://github.com/stevenfarmer/etsySellerAssistant.git
cd etsySellerAssistant

3. Install, validate, and build

Run these commands from the repository root:

npm ci
npm run validate
npm run build

• npm ci installs exactly the dependency versions recorded in package-lock.json.

• npm run validate checks formatting, lint, TypeScript types, and automated tests. It does not connect to Etsy.

• npm run build creates the JavaScript entry point Codex will launch at dist/src/index.js.

4. Add the server in Codex Desktop

Open the Codex Desktop custom MCP setup form, choose STDIO, and fill in the fields as follows. The exact menu labels can vary between Codex Desktop versions.

Example entry-point paths (replace the sample user and folder with your own):

• Windows: C:\Users\YOUR_USER\source\etsySellerAssistant\dist\src\index.js

• macOS: /Users/YOUR_USER/code/etsySellerAssistant/dist/src/index.js

Enter the executable and the script path in separate fields: put node in Command to launch, then add the script path as a single Argument. Do not paste the whole command into one field.

If Codex cannot find node, find its full path in a terminal and use that path for Command to launch:

• PowerShell: (Get-Command node).Source

• macOS Terminal: command -v node

The screenshot shows where these fields appear in the custom MCP form. Its visible command is placeholder text; do not copy it.

5. Confirm it is connected

Save the configuration, then start or reopen a Codex chat and inspect the available tools for etsySellerAssistant. Call get_setup_status. A successful response should say Etsy access is not configured.

No Etsy API key, OAuth setup, OpenAI API key, hosted service, or environment variable is needed for this scaffold.

Updating or removing the server

To update your local checkout:

git pull
npm ci
npm run validate
npm run build

If the repository path changes, update Arguments and Working directory in the Codex Desktop server entry. To remove the integration, open Codex Desktop's MCP/custom server settings and remove the etsySellerAssistant entry. The settings location and button labels can vary by app version.

Troubleshooting

Project documentation

• Architecture, data boundaries, and future design

• Development guide

• Contributing

• Security reporting

• Architecture decisions

License

GNU Affero General Public License v3.0. See LICENSE.