# siddhantbajaj/shopify-mcp-server architecture

> Architecture diagram of the GitHub repository siddhantbajaj/shopify-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddhantbajaj/shopify-mcp-server
- Repository: https://github.com/siddhantbajaj/shopify-mcp-server

## Overview

##### Main Components
- Environment/Configuration:
- Use of a .env file and environment variables. This part manages the Shopify credentials (SHOPIFY_SHOP_URL, API key, API password, and access token).
- MCP Server Core:
- Main server logic contained in src/shopify_mcp_server, specifically in server.py.
- This component is responsible for routing requests to the two main tools and handling requests over the Model Context Protocol.
- Tools/Features:
- Two sub-components/tools: “get-product-list” and “get-customer-list”. They form the business logic that interact with Shopify.
- Integration with Shopify:
- A component dedicated to communicating with Shopify using the Shopify Python API.
- Client Interfaces:
- External clients (like Claude or other AI tools) that connect to the MCP Server.
- Dependency Management & Environment:
- A note about using “uv” for virtual environment handling and dependency management.

##### Relationships and Interactions
- Data flow begins when an external client sends a request (invoked via the MCP protocol) to the MCP Server.
- The server reads configuration from the .env/environment variables to authenticate with Shopify.
- Depending on the requested tool, the server uses the Shopify Python API to retrieve either product or customer data.
- Once data is fetched, the tool formats the response according to the guidelines (e.g., list formatting as shown in the README).
- Responses are then sent back to the client.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project cleanly separates configuration/environment management, the server core, business logic tools, and external service integrations.
- Modular Design: Although the project is relatively small, consider each tool (product and customer retrieval) as a separate module/component within the MCP Server.
- External Dependencies: Highlight the integration with external services (Shopify and MCP protocol) and indicate dependency injection or similar patterns if used in the code.

##### Relevant Technologies
- Python 3.12 or higher (as required by the project).
- Shopify Python API for communication with Shopify.
- MCP (Model Context Protocol) for how the server is designed to interact with AI tools.
- UV for environment and dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client Layer
    client["External Client (e.g. Claude)"]:::external

    %% Configuration Layer
    config["Environment Configuration (.env)"]:::config

    %% MCP Server Layer
    core["MCP Server Core (server.py)"]:::core

    %% Business Tools Subgraph
    subgraph "Business Tools"
        tool1["Tool: Get Product List"]:::tools
        tool2["Tool: Get Customer List"]:::tools
    end

    %% Integration with Shopify
    shopify["Shopify Python API Integration"]:::integration

    %% Dependency Management Subgraph
    subgraph "Dependency Management"
        uvlock["uv.lock"]:::dependency
        pyproject["pyproject.toml"]:::dependency
    end

    %% Interactions
    client -->|"MCPRequest"| core
    config -->|"Credentials"| core
    uvlock -->|"Dependency"| core
    pyproject -->|"Dependency"| core

    core -->|"InvokeTool"| tool1
    core -->|"InvokeTool"| tool2

    tool1 -->|"APIRequest"| shopify
    tool2 -->|"APIRequest"| shopify

    shopify -->|"ResponseData"| tool1
    shopify -->|"ResponseData"| tool2

    tool1 -->|"ResponseData"| core
    tool2 -->|"ResponseData"| core

    core -->|"ResponseData"| client

    %% Click Events
    click core "https://github.com/siddhantbajaj/shopify-mcp-server/blob/main/src/shopify_mcp_server/server.py"
    click tool1 "https://github.com/siddhantbajaj/shopify-mcp-server/blob/main/src/shopify_mcp_server/server.py"
    click tool2 "https://github.com/siddhantbajaj/shopify-mcp-server/blob/main/src/shopify_mcp_server/server.py"
    click shopify "https://github.com/siddhantbajaj/shopify-mcp-server/blob/main/src/shopify_mcp_server/server.py"
    click uvlock "https://github.com/siddhantbajaj/shopify-mcp-server/blob/main/uv.lock"
    click pyproject "https://github.com/siddhantbajaj/shopify-mcp-server/blob/main/pyproject.toml"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef core fill:#FADBD8,stroke:#A93226,stroke-width:2px;
    classDef tools fill:#D5F5E3,stroke:#239B56,stroke-width:2px;
    classDef integration fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef dependency fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
```
