shopify-mcp-server

taharbmn/shopify-mcp-server

3.3

If you are the rightful owner of shopify-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for interacting with the Shopify Admin API using GraphQL.

Tools
6
Resources
0
Prompts
0

Shopify MCP

A Model Context Protocol (MCP) server for interacting with the Shopify Admin API using GraphQL. This package provides tools for fetching product data and order information via the Shopify Admin API.

Note: ALL THE FUNCTIONS PROPOSED ARE READ ONLY ACCESS, WE ONLY READ DATA. Note 2: Use mainly the tool query_shopify_custom_tool, IT CAN DO ANYTHING

Requirements

  • Python 3.10 or higher
  • MCP library version 1.6.0 or higher

Installation

# Clone the repository
git clone repo
cd mcp-shopify

# Install dependencies
pip install -e .

Configuration

You have two options for providing Shopify credentials:

Option 1: Environment Variables (Recommended)

Create a .env file in the project root with your Shopify credentials:

# Shopify GraphQL API credentials
SHOPIFY_SHOP_URL=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=your_access_token_here
SHOPIFY_API_VERSION=2025-01

SSL Certificate Issues on macOS

If you encounter SSL certificate verification errors (common on macOS), use the verify_ssl=False parameter with any tool:

list_products_tool(
    shop_domain="your-store.myshopify.com",
    access_token="your_access_token_here",
    verify_ssl=False  # Disables SSL verification
)

Note: Disabling SSL verification is not recommended for production use.

Available Tools

list_products_tool

Lists products from a Shopify store using GraphQL.

Optional Parameters:

  • limit (default: 10): Number of products to return (max 250)
  • status (default: "ACTIVE"): Filter products by status (ACTIVE, DRAFT, ARCHIVED)
  • query (default: ""): Additional search query
  • verify_ssl (default: False): Whether to verify SSL certificates
  • after (default: ""): Return items after this cursor (for pagination)
  • before (default: ""): Return items before this cursor (for pagination)
  • reverse (default: False): Reverse the order of the results
  • sort_key (default: "ID"): Sort products by this key (ID, TITLE, CREATED_AT, UPDATED_AT, INVENTORY, PRICE)

Example:

list_products_tool(
    limit=20,
    status="ACTIVE",
    sort_key="CREATED_AT",
    reverse=True,
    verify_ssl=False
)

Response Format:

{
  "products": [
    {
      "id": "gid://shopify/Product/123456789",
      "title": "Product Name",
      "status": "ACTIVE",
      "vendor": "Vendor Name",
      "product_type": "Type",
      "handle": "product-name",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z",
      "published_at": "2023-01-01T00:00:00Z",
      "description": "Product description",
      "description_html": "<p>Product description</p>",
      "tags": ["tag1", "tag2"],
      "total_inventory": 10,
      "price_range": {
        "min_price": {
          "amount": "10.00",
          "currency_code": "USD"
        },
        "max_price": {
          "amount": "20.00",
          "currency_code": "USD"
        }
      },
      "variants": [
        {
          "id": "gid://shopify/ProductVariant/123456789",
          "title": "Default Title",
          "price": "10.00",
          "compare_at_price": "15.00",
          "inventory_quantity": 5,
          "selected_options": [],
          "sku": "SKU123"
        }
      ],
      "images": [
        {
          "id": "gid://shopify/ProductImage/123456789",
          "url": "https://cdn.shopify.com/image.jpg",
          "alt_text": "Image description"
        }
      ],
      "cursor": "cursor_string_for_pagination"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "start_cursor_string",
    "end_cursor": "end_cursor_string"
  },
  "total_count": 1
}

list_orders_tool

Lists orders from a Shopify store using GraphQL.

Required Parameters:

  • shop_domain: Shopify shop domain (e.g., 'your-store.myshopify.com')
  • access_token: Shopify Admin API access token

Optional Parameters:

  • limit (default: 10): Number of orders to return (max 250)
  • query (default: ""): Filter string (e.g., "status:open financial_status:paid")
  • reverse (default: False): Reverse the order of the results
  • sort_key (default: "PROCESSED_AT"): Sort orders by this key (e.g., PROCESSED_AT, TOTAL_PRICE, UPDATED_AT)
  • verify_ssl (default: False): Whether to verify SSL certificates
  • after (default: ""): Return items after this cursor (for pagination)
  • before (default: ""): Return items before this cursor (for pagination)

Example:

list_orders_tool(
    limit=20,
    query="status:open",
    sort_key="TOTAL_PRICE",
    reverse=True,
    verify_ssl=False
)

Response Format:

{
  "orders": [
    {
      "id": "gid://shopify/Order/123456789",
      "name": "#1001",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z",
      "display_financial_status": "PAID",
      "display_fulfillment_status": "UNFULFILLED",
      "subtotal_price": "100.00",
      "total_price": "110.00",
      "total_shipping_price": "10.00",
      "currency_code": "USD",
      "line_items": [
        {
          "id": "gid://shopify/LineItem/111",
          "title": "Product A",
          "quantity": 1,
          "variant_id": "gid://shopify/ProductVariant/222",
          "variant_title": "Small",
          "price": "50.00",
          "sku": "SKU-A-S",
          "original_unit_price": "50.00",
          "currency_code": "USD"
        }
      ],
      "cursor": "cursor_string_for_pagination"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "start_cursor_string",
    "end_cursor": "end_cursor_string"
  },
  "count_on_page": 1
}

list_inventory_items_tool

Lists inventory items from a Shopify store using GraphQL.

Optional Parameters:

  • limit (default: 10): Number of inventory items to return (max 250)
  • query (default: ""): Additional search query (e.g., "sku:MY-SKU-123", "tracked:true")
  • verify_ssl (default: False): Whether to verify SSL certificates
  • after (default: ""): Return items after this cursor (for pagination)
  • before (default: ""): Return items before this cursor (for pagination)
  • reverse (default: False): Reverse the order of the results

Example:

list_inventory_items_tool(
    limit=50,
    query="tracked:true",
    verify_ssl=False
)

Response Format:

{
  "inventory_items": [
    {
      "id": "gid://shopify/InventoryItem/123456789",
      "sku": "SKU123",
      "tracked": true,
      "requires_shipping": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z",
      "inventory_levels": [
        {
          "available": 10,
          "on_hand": 10,
          "location_id": "gid://shopify/Location/987654321",
          "location_name": "Main Warehouse",
          "updated_at": "2023-01-02T00:00:00Z"
        }
      ],
      "cursor": "cursor_string_for_pagination"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "start_cursor_string",
    "end_cursor": "end_cursor_string"
  },
  "count_on_page": 1
}

list_marketing_activities_tool

Lists marketing activities from a Shopify store using GraphQL.

Optional Parameters:

  • limit (default: 10): Number of activities to return (max 250)
  • query (default: ""): Filter string (e.g., "title:'Summer Sale'")
  • marketing_activity_ids (default: None): Filter by a list of marketing activity GIDs.
  • remote_ids (default: None): Filter by a list of remote IDs.
  • reverse (default: False): Reverse the order of the results
  • sort_key (default: "CREATED_AT"): Sort activities by this key (e.g., CREATED_AT, UPDATED_AT, TITLE)
  • verify_ssl (default: False): Whether to verify SSL certificates
  • after (default: ""): Return items after this cursor (for pagination)
  • before (default: ""): Return items before this cursor (for pagination)

Example:

list_marketing_activities_tool(
    limit=15,
    query="status:ACTIVE",
    sort_key="TITLE",
    verify_ssl=False
)

Response Format:

{
  "marketing_activities": [
    {
      "id": "gid://shopify/MarketingActivity/123",
      "title": "Summer Sale Campaign",
      "status": "ACTIVE",
      "sourceAndMedium": "facebook / cpc",
      "app": {
        "id": "gid://shopify/App/456",
        "title": "Facebook Ads App"
      },
      "budget": {
        "budgetType": "DAILY",
        "total": {
          "amount": "100.00",
          "currencyCode": "USD"
        }
      },
      "campaignId": "campaign_12345",
      "createdAt": "2023-06-01T10:00:00Z",
      "description": "Daily budget for summer sale.",
      "errors": [],
      "remoteId": "fb_ad_789",
      "updatedAt": "2023-06-15T12:30:00Z",
      "cursor": "cursor_string_for_pagination"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "start_cursor_string",
    "end_cursor": "end_cursor_string"
  },
  "count_on_page": 1
}

query_shopify_custom_tool

Executes custom GraphQL queries or mutations against the Shopify Admin API. This tool also attempts to ensure the relevant GraphQL schema is cached on the server and reports this status. This is useful for advanced data retrieval or operations not covered by other specific tools.

Required Parameters:

  • query_str: The GraphQL query or mutation string to execute.

Optional Parameters:

  • variables (default: None): A dictionary of variables for the GraphQL query.
  • allow_mutations (default: False): Set to true to allow mutation operations.

Example:

query_shopify_custom_tool(
    query_str=\'\'\':
        query {
          shop {
            name
            currencyCode
          }
        }
    \'\'',
)

Response Format:

{
  "query_result": {
    "data": {
      "shop": {
        "name": "Your Awesome Store",
        "currencyCode": "USD"
      }
    }
    // or "errors": [...] if the query fails
  },
  "schema_priming_status": "Info: Schema for API version '2025-01' was confirmed available or cached on the server."
}

manage_shopify_schema_tool

Manages the Shopify GraphQL schema cache on the server. This allows for explicit control over fetching, retrieving status, listing cached versions, and clearing the schema cache.

Required Parameters:

  • action: The action to perform. Supported actions:
    • 'fetch': Fetches and caches the schema for a given API version.
    • 'get_schema': Retrieves the schema for a given API version from cache if available, otherwise fetches and caches it. (Returns a status message, not the full schema).
    • 'list_cached_versions': Lists API versions for which schemas are currently cached.
    • 'clear_cache': Clears the schema cache. Can specify an api_version to clear only that version, otherwise clears the entire cache.

Optional Parameters (Contextual based on action):

  • api_version (default: system default, e.g., "2025-01" for 'fetch'/'get_schema'): The Shopify API version. Used by 'fetch', 'get_schema'. Optional for 'clear_cache' (to target a specific version).
  • verify_ssl (default: False): Whether to verify SSL certificates for 'fetch'/'get_schema'.

Examples:

Fetching a schema:

manage_shopify_schema_tool(
    action="fetch",
    shop_domain="your-store.myshopify.com",
    access_token="your_access_token_here",
    api_version="2025-01"
)

Listing cached schema versions:

manage_shopify_schema_tool(action="list_cached_versions")

Clearing the entire cache:

manage_shopify_schema_tool(action="clear_cache")

Response Format (Example for 'fetch'):

{
  "status": "success",
  "message": "Schema for API version 2025-01 fetched and cached.",
  "api_version": "2025-01"
}

Response Format (Example for 'list_cached_versions'):

{
  "status": "success",
  "cached_api_versions": ["2025-01", "2023-10"]
}

Running the Server

Run the MCP server with:

python main.py

Using with Claude

You can use this MCP server with Claude in the following ways:

Installing in Claude Desktop

mcp install main.py -f .env

Then restart Claude Desktop. The server should appear in Claude's MCP server list.

Using with MCP Server

Once installed, you can use the tools in Claude by:

  1. Starting a new conversation

  2. Using the tool directly:

    Could you list 5 of my Shopify products?

  3. If credentials aren't set up, you can provide them directly:

    Please list my Shopify products with shop_domain="my-store.myshopify.com" and access_token="my_token"

Troubleshooting

SSL Certificate Issues

If you experience SSL certificate errors (especially on macOS), use the verify_ssl=False parameter:

list_products_tool(
    shop_domain="your-store.myshopify.com",
    access_token="your_access_token_here",
    verify_ssl=False
)

Authentication Issues

  • Verify your access token has the correct API scopes (read_products, read_orders)
  • Ensure your shop URL is in the correct format (your-store.myshopify.com)
  • Check that your access token hasn't expired

Getting a Shopify Access Token

  1. Go to your Shopify admin panel
  2. Navigate to Apps > App and sales channel settings
  3. Click "Develop apps" and then "Create an app"
  4. Set up the app with appropriate API scopes (at minimum: read_products, read_orders)
  5. Install the app to your store
  6. Copy the access token for use with these tools