etsy-mcp-server

Local Etsy MCP 服务

通过本地 stdio MCP 服务，将 AI 客户端连接到 Etsy 商店。这些工具会读取商店和商品信息，但无法修改商品、处理订单或发送消息。你的 Etsy 应用凭据和 OAuth 令牌会保存在操作系统的凭据存储中。

准备电脑

• 安装 Node.js 24 或更高版本，包括 npm。使用 node --version 和 npm --version 检查。
• 获取你自己的、已获批准的 Etsy 开发者应用 keystring 和共享密钥。
• 如有需要，在 Etsy 应用中注册 http://localhost:3030/oauth/redirect。Etsy Quick Start 演示了 localhost 回调。身份验证指南也介绍了 HTTPS 回调。如果 Etsy 拒绝你的应用使用本地回调，设置会停止，且不会保存凭据。
• 在 Windows 上，请在同一个 Windows 账户下运行设置程序和 AI 客户端，并确保 Credential Manager 可用。
• 在 macOS 上，解锁登录 Keychain，并在与 AI 客户端相同的账户下运行设置程序。
• 在 Linux 上，请使用已解锁的 Secret Service 实现，例如 GNOME Keyring 或 KeePassXC，并确保可通过同一个桌面 D-Bus 会话访问。没有明文或 Linux 内核密钥环回退方式。

WSL 发行版、容器、远程开发主机和本机桌面属于不同的运行环境。保存在 Windows Credential Manager 中的连接不会自动在 WSL 中可用。请在同一环境和账户下运行设置程序和 MCP 进程。

传递给本地 OAuth API 的自定义回调 URI 必须使用环回 HTTP（localhost、127.0.0.1 或 [::1]），并指定 1 到 65535 之间的端口。系统会在打开浏览器前拒绝不支持的回调。

连接商店

在 macOS 或 Linux 的本地交互式终端中运行此命令：

npx --yes @profplum700/etsy-mcp-server@latest setup

在 Windows 上，请在 PowerShell 中运行以下命令。显式使用 .cmd 可避免 npm 命令代理受到 PowerShell 脚本执行策略的限制：

npx.cmd --yes @profplum700/etsy-mcp-server@latest setup

在隐藏提示中输入 keystring 和共享密钥。不要将它们粘贴到 AI 聊天、配置文件、环境变量或命令参数中。设置程序会打开 Etsy，并且只请求 shops_r 和 listings_r。它会验证商店，然后将凭据保存在操作系统的凭据存储中。

设置程序询问是否注册 Codex 时，只有在 Codex 是你的客户端时才选择“是”。否则请选择“否”，并按照下方相关部分操作。客户端注册不会替代 Etsy 设置。

示例使用 npm 的 latest 版本。如需进行受控升级，请在设置命令和客户端配置中都将 @latest 替换为确切的已发布版本。源码检出或尚未合并的 PR 可能包含 npm 尚未发布的功能。

将服务添加到 AI 客户端

这些配置使用本地 stdio。请保留现有配置条目，只添加 etsy-mcp-server 条目。不要配置 HTTP URL，也不要将 Etsy 密钥放入这些文件中。

Claude Desktop

打开 Settings > Developer > Edit Config。标准配置文件在 macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上为 %APPDATA%\Claude\claude_desktop_config.json。在 Linux 上，请使用 Edit Config 定位文件，不要假设其路径。请参阅官方本地服务指南。

在 macOS 或 Linux 上，添加：

{
	"mcpServers": {
		"etsy-mcp-server": {
			"command": "npx",
			"args": ["--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
		}
	}
}

在 Windows 上，使用命令处理器启动 npm 命令代理：

{
	"mcpServers": {
		"etsy-mcp-server": {
			"command": "cmd.exe",
			"args": ["/d", "/c", "npx.cmd", "--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
		}
	}
}

退出并重新打开 Claude Desktop。检查服务及其工具是否显示。导入 GitHub 仓库或 ZIP 文件不等于安装 npm MCP。此仓库目前尚未发布经过验证的 .mcpb 扩展。请参阅扩展可行性评估。

Claude Code

在 macOS 或 Linux 上：

claude mcp add --transport stdio --scope user etsy-mcp-server -- npx --yes @profplum700/etsy-mcp-server@latest serve
claude mcp list

在原生 Windows 的 PowerShell 中：

claude mcp add --transport stdio --scope user etsy-mcp-server -- cmd.exe /d /c npx.cmd --yes @profplum700/etsy-mcp-server@latest serve
claude mcp list

在 Claude Code 中使用 /mcp 检查连接。Claude Code 文档介绍了用户级作用域和 -- 分隔符。如果你在 WSL 中使用 Claude Code，请遵循 WSL 中的 Linux 设置要求。

OpenAI Codex

如果设置已添加该服务，请勿重复添加。否则，在 macOS 或 Linux 上：

codex mcp add etsy-mcp-server -- npx --yes @profplum700/etsy-mcp-server@latest serve
codex mcp list

在原生 Windows 的 PowerShell 中：

codex mcp add etsy-mcp-server -- cmd.exe /d /c npx.cmd --yes @profplum700/etsy-mcp-server@latest serve
codex mcp list

重启相关的本地 Codex 客户端，并在 CLI 中检查 /mcp。Codex MCP 文档还介绍了通过 config.toml 进行配置。此本地命令不会为托管云任务配置访问权限。

Cursor

将适用于你操作系统的 Claude Desktop JSON 配置块添加到个人 Cursor 配置中：

• macOS 和 Linux：~/.cursor/mcp.json。
• Windows：%USERPROFILE%\.cursor\mcp.json。

在 etsy-mcp-server 对象中添加 "type": "stdio"。如果只用于一个项目，请改用该项目中的 .cursor/mcp.json。打开 Cursor 的 MCP 设置，确认 etsy-mcp-server 已启用并已连接。这些位置和 mcpServers 结构遵循 Cursor 的 MCP 文档。

VS Code with GitHub Copilot

对于当前的 Copilot harness 会话，打开 聊天：打开自定义项 > MCP 服务器 > 添加服务器。选择 命令（stdio） 和全局 Copilot 目标位置。输入适用于你操作系统的 Claude Desktop 配置块中的命令和参数数组。个人配置文件为 $COPILOT_HOME/mcp-config.json；如果未设置该变量，则为 ~/.copilot/mcp-config.json。它使用 mcpServers。请参阅添加 MCP 服务器。

对于 VS Code 配置格式，请运行 MCP：打开用户配置。在 macOS 或 Linux 上，添加：

{
	"servers": {
		"etsy-mcp-server": {
			"type": "stdio",
			"command": "npx",
			"args": ["--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
		}
	}
}

在 Windows 上，将该服务的 command 和 args 替换为：

{
	"command": "cmd.exe",
	"args": ["/d", "/c", "npx.cmd", "--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
}

保留 "type": "stdio"。若要使用本地工作区配置，请使用 .vscode/mcp.json。不要将其 servers 封装结构复制到通用 Copilot 格式中。配置参考介绍了这些格式的区别。重启服务，检查其输出，并在选定的 Copilot 会话中启用其工具。远程工作区需要自己的运行时和凭据存储访问权限。

Gemini CLI

将适用于你操作系统的 Claude Desktop JSON 配置块合并到用户设置中：

• macOS 和 Linux：~/.gemini/settings.json。
• Windows：%USERPROFILE%\.gemini\settings.json。

保留 mcpServers 旁边的所有现有设置。重启 Gemini CLI，然后运行 /mcp 检查连接。请保持工具确认功能处于启用状态。Gemini CLI MCP 指南介绍了此格式以及可选的 gemini mcp add 注册命令。

验证连接

让客户端调用 etsy_get_my_shop，并显示返回的店铺 ID 和名称。确认它们与预期的店铺一致。然后调用 etsy_list_active_listings，并设置 limit: 1，获取一个有效商品。仅配置服务或成功启动，并不能证明已获得 Etsy 访问权限。

服务通过 stdin 和 stdout 通信。诊断信息输出到 stderr。手动运行 serve 命令时，它会等待 MCP 客户端，不是交互式 shell。

每个服务进程在启动时都会绑定到当前活动店铺。更改活动店铺不会将正在运行的 AI 会话切换到其他店铺。更改店铺后，请重启该客户端的 MCP 服务。成功的工具结果会标明其查询的店铺。

诊断本地问题

在与客户端处于同一环境的终端中运行诊断：

npx --yes @profplum700/etsy-mcp-server@latest doctor
npx --yes @profplum700/etsy-mcp-server@latest doctor --json

在 Windows 上，请使用 npx.cmd 代替 npx。诊断会检查本地前置条件和已保存连接的就绪状态，不会向 Etsy 发起请求，也不会更改已保存的凭据。它无法验证网络访问、OAuth 刷新、客户端注册或实时 API 权限。其 JSON 报告包含 schema_version、ok，以及一个含有 code、status 和 message 的 checks 数组。状态为 pass、warn 或 fail。失败时返回退出代码 1。只有警告时返回退出代码 0。它不会输出店铺名称、ID、本地路径或凭据值。请按照报告中的操作处理。尚未发布的源码检出版本必须在本地构建并运行，才能测试其新增的诊断功能。

症状	操作
客户端输出中缺少 node 或 npx	安装 Node.js 24 或更高版本，然后重启客户端，使其继承 PATH。
PowerShell 拒绝运行 npx.ps1	在终端中使用 npx.cmd。在客户端中使用上述 Windows 配置。
Linux Secret Service 不可用	启动并解锁桌面密钥环。在同一 D-Bus 会话中运行客户端。
macOS 拒绝访问 Keychain	解锁登录钥匙串，并查看针对 Node 进程的操作系统访问提示。
没有已保存的连接或作用域遭拒	在交互式终端中运行设置，并且只批准 shops_r 和 listings_r。
设置无法绑定回调端口	关闭占用端口 3030 的进程，然后重新运行设置。不要将回调地址改为未注册的地址。
终端可以运行，但图形客户端找不到命令	在 macOS 或 Linux 上使用 command -v npx，或在 Windows 上使用 where.exe npx.cmd 查找可执行文件。在客户端中使用其绝对路径。对于包含空格的 Windows 路径，优先使用下方的直接 Node 启动方式。
服务已连接，但返回的是之前的店铺	选择目标配置文件，然后在该客户端中重启 MCP 服务。

为避免 npm 启动时下载内容以及 Windows 命令 shim 的引号问题，请使用 npm install --global @profplum700/etsy-mcp-server@latest 全局安装经过审核的版本。使用 npm root --global 查找其包目录，并使用 node -p "process.execPath" 查找 Node。将绝对路径的 Node 可执行文件配置为 command，并将绝对路径 <npm-root>/@profplum700/etsy-mcp-server/dist/cli.js 和 serve 分别设为 args。在 Windows 上，请将路径保留为 JSON 字符串，并对反斜杠进行转义。此备用方式仍需要使用相同的操作系统凭据存储。

管理店铺配置文件

再次运行设置即可连接其他店铺。每次成功设置都会添加或更新该店铺，并将其设为活动店铺，同时保留其他店铺。

npx --yes @profplum700/etsy-mcp-server@latest status
npx --yes @profplum700/etsy-mcp-server@latest use "Test Shop"
npx --yes @profplum700/etsy-mcp-server@latest setup --reuse-app --manual-browser

最后一条命令会重用已保存的开发者应用凭据。在已登录目标 Etsy 账号的浏览器配置文件中打开其授权 URL。

npx --yes @profplum700/etsy-mcp-server@latest disconnect
npx --yes @profplum700/etsy-mcp-server@latest disconnect --shop "Test Shop"
npx --yes @profplum700/etsy-mcp-server@latest disconnect --all
npx --yes @profplum700/etsy-mcp-server@latest remove-codex

在 Windows 上使用 npx.cmd。断开连接前会询问是否清除凭据。不带选项时，操作目标为活动店铺。--shop 用于指定一个已保存的店铺，--all 则会清除所有店铺。移除 Codex 配置不会影响已保存的 Etsy 连接。

可用工具

• etsy_get_my_shop 可读取已连接店铺的名称、ID、货币、在售商品数量和 URL。
• etsy_list_active_listings 可返回在售商品的标题、基础价格、货币、URL 和状态。每页可请求 1 至 50 件商品，偏移量最高为 10,000。
• etsy_get_listing 可读取已连接店铺商品的标题、描述、标签、材料、语言、状态、基础价格和 URL，以供内容审核。该工具会拒绝读取其他店铺拥有的商品。
• etsy_get_listing_inventory 可返回已连接店铺商品的变体选项、价格和数量。请持续读取 next_offset，直到其值为 null。每页按每个商品条目返回一条记录，因此同一商品可能出现多次。

审核价格范围时，请分页读取在售商品并筛选其基础价格。变体价格请使用库存工具。这些工具无法确定配送资格、利润、订单收入或转化率。所有工具均为只读，且请求的权限范围仅限 shops_r 和 listings_r。

客户端说明已于 2026-10-24 根据所链接的官方文档核验。说明描述的是受支持的配置格式，并不表示已对每种客户端与操作系统组合进行测试。已执行的平台测试请参阅实现报告和 CI 结果。