freewebstore-mcp

Automate your Store

This is a MCP (Model Context Protocol) server for the Freewebstore e-commerce platform API. It exposes the full Freewebstore REST API as MCP tools, enabling AI assistants like Claude Desktop to manage your online store.

You can use this to have Claude Desktop manage everything in your store from stock levels and product images to customer orders.

Features

• Full coverage of 10 Freewebstore API resource areas
• 50+ MCP tools for managing categories, products, orders, customers, reviews, brands, gift cards, pages, analytics, and store settings
• stdio transport for Claude Desktop (Including CoWork) and other MCP clients
• API key authentication via environment variable
• Built-in server instructions and workflow prompts that orient AI agents automatically on connection (your agent will know just what to do)
• Zero runtime dependencies beyond the MCP SDK and Node.js built-ins

Installation

Open your terminal application and run the following command.

npm install -g freewebstore-mcp

Note: you may need to install npm

Claude Desktop Quick Start

Now edit your claude_desktop_config.json in your favourite editor to add the freewebstore entry to the mcpServers section. If the file already has content (such as preferences), add mcpServers alongside it do not replace the existing config:

{
  "preferences": {
    "...your existing preferences..."
  },
  "mcpServers": {
    "freewebstore": {
      "command": "npx",
      "args": [
        "-y",
        "freewebstore-mcp"
      ],
      "env": {
        "FREEWEBSTORE_API_KEY": "your-api-key-here"
      }
    }
  }
}

If you already have other MCP servers configured, add the freewebstore block inside the existing mcpServers object.

Auto-approve tools

By default, Claude Desktop will ask for permission each time a tool is called. To auto-approve all freewebstore tools, add the alwaysAllow array to your server config:

"freewebstore": {
  "command": "npx",
  "args": [
    "-y",
    "freewebstore-mcp"
  ],
  "env": {
    "FREEWEBSTORE_API_KEY": "your-api-key-here"
  },
  "alwaysAllow": [
    "fws_category_list",
    "fws_category_get",
    "fws_category_create",
    "fws_category_update",
    "fws_category_delete",
    "fws_product_list",
    "fws_product_get",
    "fws_product_create",
    "fws_product_update",
    "fws_product_delete",
    "fws_product_search",
    "fws_product_search_advanced",
    "fws_product_featured",
    "fws_product_offers",
    "fws_product_new",
    "fws_product_low_stock",
    "fws_product_stock_audit",
    "fws_product_stock_all",
    "fws_product_copy",
    "fws_order_list",
    "fws_order_get",
    "fws_order_update_status",
    "fws_order_add_tracking",
    "fws_order_dispatch",
    "fws_order_add_note",
    "fws_order_counts",
    "fws_order_mark_read",
    "fws_order_abandoned",
    "fws_customer_list",
    "fws_customer_get",
    "fws_customer_create",
    "fws_customer_update",
    "fws_customer_delete",
    "fws_customer_loyalty",
    "fws_customer_loyalty_history",
    "fws_review_list",
    "fws_review_pending",
    "fws_review_by_product",
    "fws_review_get",
    "fws_review_update",
    "fws_review_delete",
    "fws_brand_list",
    "fws_brand_get",
    "fws_brand_create",
    "fws_brand_update",
    "fws_brand_delete",
    "fws_giftcard_list",
    "fws_giftcard_get",
    "fws_page_list",
    "fws_page_get",
    "fws_page_create",
    "fws_page_update",
    "fws_page_delete",
    "fws_analytics_summary",
    "fws_analytics_product_summary",
    "fws_store_get",
    "fws_store_settings",
    "fws_store_health",
    "fws_store_usage",
    "fws_store_slideshow",
    "fws_store_milestones",
    "fws_store_discounts",
    "fws_store_checkout"
  ]
}

Config file location

| Platform | Path | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Environment Variables

| Variable | Required | Description | |---|---|---| | FREEWEBSTORE_API_KEY | Yes | Your Freewebstore API key | | FREEWEBSTORE_API_URL | No | Override base URL (default: https://api.freewebstore.com) |

Technical Documentation

Available Tools

Categories

| Tool | Description | |---|---| | fws_category_list | List all store categories | | fws_category_get | Get a single category by ID | | fws_category_create | Create a new category | | fws_category_update | Update an existing category | | fws_category_delete | Delete a category |

Products

| Tool | Description | |---|---| | fws_product_list | List products with pagination and sorting | | fws_product_get | Get a single product by ID | | fws_product_create | Create a new product | | fws_product_update | Update an existing product | | fws_product_delete | Delete a product | | fws_product_search | Search products by text | | fws_product_search_advanced | Advanced search with filters | | fws_product_featured | Get featured products | | fws_product_offers | Get products on sale | | fws_product_new | Get recently added products | | fws_product_low_stock | Get low stock products | | fws_product_stock_audit | Get stock audit trail | | fws_product_stock_all | Get complete stock history | | fws_product_copy | Duplicate a product |

Orders

| Tool | Description | |---|---| | fws_order_list | List orders with filtering | | fws_order_get | Get full order details | | fws_order_update_status | Update order status | | fws_order_add_tracking | Add tracking information | | fws_order_dispatch | Mark order as dispatched | | fws_order_add_note | Add a note to an order | | fws_order_counts | Get order count breakdown | | fws_order_mark_read | Mark order as read | | fws_order_abandoned | Get abandoned checkouts |

Customers

| Tool | Description | |---|---| | fws_customer_list | List customers | | fws_customer_get | Get a single customer | | fws_customer_create | Create a new customer | | fws_customer_update | Update a customer | | fws_customer_delete | Delete a customer | | fws_customer_loyalty | Get loyalty balance | | fws_customer_loyalty_history | Get loyalty transaction history |

Reviews

| Tool | Description | |---|---| | fws_review_list | List all reviews | | fws_review_pending | List pending reviews | | fws_review_by_product | Get reviews for a product | | fws_review_get | Get a single review | | fws_review_update | Approve/reply to a review | | fws_review_delete | Delete a review |

Brands

| Tool | Description | |---|---| | fws_brand_list | List all brands | | fws_brand_get | Get a single brand | | fws_brand_create | Create a new brand | | fws_brand_update | Update a brand | | fws_brand_delete | Delete a brand |

Gift Cards

| Tool | Description | |---|---| | fws_giftcard_list | List all gift cards | | fws_giftcard_get | Get a gift card with transactions |

Pages

| Tool | Description | |---|---| | fws_page_list | List all CMS pages | | fws_page_get | Get a single page | | fws_page_create | Create a new page | | fws_page_update | Update a page | | fws_page_delete | Delete a page |

Analytics

| Tool | Description | |---|---| | fws_analytics_summary | Get order analytics summary | | fws_analytics_product_summary | Get product analytics summary |

Store

| Tool | Description | |---|---| | fws_store_get | Get store details | | fws_store_settings | Get store settings | | fws_store_health | Get store health score | | fws_store_usage | Get resource usage statistics | | fws_store_slideshow | Get slideshow configuration | | fws_store_milestones | Get store milestones | | fws_store_discounts | Get discount rules | | fws_store_checkout | Get checkout configuration |

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Build
npm run build

# Start the server
FREEWEBSTORE_API_KEY=your-key npm start

License

MIT