Python Shopify MCP Server for Claude

面向 Claude 的 Python Shopify MCP 服务

这是一个 Model Context Protocol（MCP）服务的 Python 实现，可让 Claude AI 无缝访问您的 Shopify 商店数据。通过此集成，Claude 可以访问产品目录、客户信息和订单详情，从而为电商任务提供更智能、更贴合上下文的帮助。

🌟 功能

• 与 Claude 无缝集成

  • 直接在 Claude 对话中访问您的 Shopify 商店数据
  • 无需复制粘贴数据，也无需在应用之间切换
  • Claude 可以分析并推理您的商店信息

• 全面访问产品信息

  • 查询完整的产品目录
  • 访问详细的产品信息、变体和库存
  • 按标题、供应商或产品类型搜索产品

• 客户洞察

  • 获取客户档案和购买记录
  • 访问联系信息和收货地址
  • 查看消费模式和下单频率

• 订单管理

  • 访问订单详情、订单项和履约状态
  • 查看付款信息和配送详情
  • 分析订单指标和模式

• 商店信息

  • 访问 Shopify 商店的元数据
  • 查看货币、区域设置和时区
  • 获取店主和业务详情

📋 前提条件

• Python 3.10 或更高版本（推荐 Python 3.12）
• 拥有 Admin API 访问凭据的 Shopify 商店
• 已安装 Claude Desktop
• 了解基本的终端命令

🚀 快速开始

1. 克隆代码库

git clone https://github.com/yourusername/shopify-mcp-server.git
cd shopify-mcp-server

2. 设置 Python 环境

创建并激活虚拟环境：

# Create virtual environment
python -m venv .venv-py312

# Activate on macOS/Linux
source .venv-py312/bin/activate

# Activate on Windows
.venv-py312\Scripts\activate

3. 安装依赖项

pip install ShopifyAPI fastmcp python-dotenv

4. 配置 Shopify 凭据

在项目根目录中创建 .env 文件：

SHOPIFY_SHOP_URL=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=your_access_token_here

或者使用 API 密钥进行身份验证：

SHOPIFY_SHOP_URL=your-store.myshopify.com
SHOPIFY_API_KEY=your_api_key_here
SHOPIFY_PASSWORD=your_private_app_password_here

您也可以使用设置脚本进行更安全的配置：

chmod +x setup_credentials.sh
./setup_credentials.sh

5. 测试配置

运行以下命令，验证设置：

chmod +x test_env.sh
./test_env.sh

6. 将服务设为可执行

chmod +x claude_server.sh

🔧 配置 Claude Desktop

要将 Shopify MCP 服务添加到 Claude Desktop：

1. 打开 Claude Desktop，然后点击设置图标

2. 在 MCP 设置部分，添加新服务并填写以下设置：

   • 名称：Shopify Store
   • 命令：/full/path/to/shopify-mcp-server/claude_server.sh
   • 工作目录：/full/path/to/shopify-mcp-server

   请务必将 /full/path/to/ 替换为实际文件路径。

3. 保存配置并重启 Claude Desktop

4. Claude 现在应该可以访问您的 Shopify 商店数据了！

🧠 在 Claude 中使用 Shopify 工具

配置完成后，您可以在对话中让 Claude 使用 Shopify 工具。以下是一些示例：

• “显示我商店中销量最高的 5 款产品”
• “找出所有消费超过 $100 的客户”
• “搜索供应商为 X 的产品”
• “获取我近期订单的详情”
• “我的产品目录中的平均价格是多少？”

Claude 将通过 MCP 服务访问您的 Shopify 数据，并根据商店中的实际信息提供有价值的回答。

🔒 安全最佳实践

• 凭据保护：将 API 凭据存储在权限受限的文件中（600）
• 只读访问：MCP 服务只会读取数据，无法修改您的商店
• 最小权限：配置 Shopify API 访问权限时，仅授予所需的最低权限
• 仅限本地：服务在您的计算机上本地运行，以最大限度保障安全
• 轮换凭据：定期轮换 API 密钥和令牌

❓ 故障排除

如果您在使用 Shopify MCP 服务时遇到问题：

1. 检查您的凭据

   • 确认 .env 文件中的 Shopify API 凭据正确无误
   • 确保店铺 URL 格式正确（例如，your-store.myshopify.com）

2. 验证 Claude Desktop 配置

   • 确保 Claude Desktop 设置中的路径是绝对路径且正确无误
   • 检查工作目录是否设置正确
   • 更改配置后，重启 Claude Desktop

3. 检查服务运行情况

   • 确保 claude_server.sh 具有可执行权限
   • 如果遇到权限问题，请运行 chmod +x claude_server.sh

如需了解更详细的设置信息，请参阅 CLAUDE_SETUP.md 文件。

📚 可用的 MCP 工具

Shopify MCP 服务为 Claude 提供以下功能：

工具	描述
get_products	从您的 Shopify 店铺获取产品列表
get_product_details	获取特定产品的详细信息
get_customers	从您的店铺获取客户列表
get_customer_details	获取特定客户的详细信息
get_orders	从您的店铺获取订单列表
search_products	按名称、类型或供应商搜索产品
get_store_info	获取您的 Shopify 店铺信息

🏗️ 项目结构

• shopify_mcp_fastmcp.py - 使用 FastMCP 实现的 Python MCP 服务主程序
• claude_server.sh - 用于为 Claude 启动 Python MCP 服务的 Bash 脚本
• setup_credentials.sh - 用于安全配置凭据的辅助脚本
• test_env.sh - 用于验证环境设置的诊断工具
• .env.example - 环境变量示例文件
• CLAUDE_SETUP.md - Claude Desktop 的详细设置说明

🧪 技术栈

• Python：核心实现语言（兼容 3.10+，推荐使用 3.12）
• FastMCP：用于高效实现 MCP 的 Python 库
• Shopify API：用于集成 Shopify API 的官方 Python 客户端
• Python-dotenv：用于安全管理环境变量

🌐 了解更多

• Model Context Protocol 文档
• Claude Desktop 文档
• Shopify API 文档
• FastMCP Python 库

📄 许可证

MIT 许可证

🤝 参与贡献

欢迎参与贡献！请随时提交拉取请求。

1. Fork 此代码仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建拉取请求

📬 联系方式

如果您有任何问题或需要设置方面的帮助，请在 GitHub 代码仓库中提交 Issue。

---

为 Claude 和 Shopify 爱好者倾心打造 ❤️