Skip to main content
Glama
Sign In
Turbify Store MCP Server

Turbify Store MCP Server

by benpeke
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Turbify Store MCP Server

A Model Context Protocol (MCP) server for managing Turbify Store catalogs. This server provides tools to create, update, delete, and search catalog items through the Turbify Store Catalog API.

Features

  • Item Management: Create, update, and delete catalog items

  • Search: Search through your catalog using keywords

  • Configuration: View and manage store settings

  • Error Handling: Comprehensive error handling and reporting

  • Documentation: Built-in API documentation via MCP resources

Related MCP server: mouser-search-mcp

Installation

  1. Clone this repository:

git clone <your-repo-url>
cd turbify-mcp

  1. Initialize with uv (recommended):

uv init .
uv add fastmcp pydantic requests urllib3

Or install with pip:

pip install -e .

Configuration

Set the following environment variables:

export TURBIFY_STORE_ID="your_store_id"
export TURBIFY_CONTRACT_TOKEN="your_contract_token"

Or create a .env file:

TURBIFY_STORE_ID=your_store_id
TURBIFY_CONTRACT_TOKEN=your_contract_token

Usage

Running the Server

python src/turbify_mcp/server.py

Or if installed:

turbify-mcp

Using MCP Inspector

mcp-inspector "python run_server.py"

Available Tools

create_catalog_item

Create a new item in your catalog:

create_catalog_item(
    item_id="ITEM123",
    name="Sample Product",
    table_id="TABLE1",
    price=29.99,
    sale_price=24.99,
    orderable="yes",
    taxable="yes"
)

update_catalog_item

Update an existing item:

update_catalog_item(
    item_id="ITEM123",
    name="Updated Product Name",
    price=34.99
)

delete_catalog_item

Delete an item:

delete_catalog_item(item_id="ITEM123")

search_catalog_items

Search for items:

search_catalog_items(
    keyword="shirt",
    start_index=1,
    end_index=50
)

get_store_config

Get current configuration:

get_store_config()

MCP Integration

This server can be used with any MCP-compatible client, such as:

  • Claude Desktop

  • Custom MCP clients

  • Development tools that support MCP

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "turbify-store": {
      "command": "python",
      "args": ["path/to/turbify-store-mcp/src/turbify_store_mcp/server.py"],
      "env": {
        "TURBIFY_STORE_ID": "your_store_id",
        "TURBIFY_CONTRACT_TOKEN": "your_contract_token"
      }
    }
  }
}

API Response Format

All tools return JSON responses with the following structure:

Success Response

{
  "status": "success",
  "messages": [
    {
      "code": "SUCCESS",
      "message": "Operation completed successfully"
    }
  ],
  "items": [...],  // For search operations
  "item_ids": [...] // For some operations
}

Error Response

{
  "status": "error",
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Error description"
    }
  ]
}

Development

Setting up for development:

# Install with development dependencies
uv add --dev pytest pytest-asyncio black mypy

# Run tests
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy src/

Project Structure

turbify-mcp/
├── src/
│   └── turbify_mcp/
│       ├── __init__.py
│       └── server.py
├── tests/
├── pyproject.toml
├── README.md
└── .env

Requirements

  • Python 3.8+

  • Turbify Store API credentials

  • FastMCP

  • Pydantic v2

  • Requests

Limitations

  • Maximum 1000 items per search query (Turbify API limit)

  • Rate limiting as per Turbify Store API terms

  • XML-based API (handled internally)

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

License

[Add your license information here]

Support

For issues related to:

  • This MCP server: Create an issue in this repository

  • Turbify Store API: Consult Turbify Store API documentation

  • MCP protocol: Check the Model Context Protocol specification

Available Tools

6 tools
advanced_search_catalog_itemsB
    Advanced search for items in the Turbify Store catalog with multiple criteria.
    
    Args:
        criteria_list: List of criteria dictionaries, each with 'attribute', 'operator', and 'value'
                      Example: [{"attribute": "price", "operator": "gt", "value": "10.00"}]
        match_type: How to match criteria - "all" (AND) or "any" (OR) (default: "all")
        table_id: Optional table ID to search within
        start_index: Starting index for pagination (default: 1)
        end_index: Ending index for pagination (default: 100, max: 1000)
    
    Returns:
        JSON string with search results

Inputs: criteria_list (required), match_type, table_id, start_index, +1 more. Returns: result

create_itemsB
    Create items in Turbify Merchant Solutions catalog using the Catalog API.
    HTML included in the request values must be contained within CDATA tags.

    Args:
        items: List of item dictionaries to create. Each item must have:
            - id (str): Unique item ID
            - name (str): Item name
            - price (float): Item price
            - orderable (bool): Whether item is orderable
            - taxable (bool): Whether item is taxable
            - table_id (str): Table ID where item belongs
            - custom_data (list, optional): List of {"name": str, "value": str} custom attributes

    Returns:
        JSON string with creation results including success status and any error messages

Inputs: items (required). Returns: result

delete_itemsB
    Delete multiple items in a single operation.
    
    Args:
        item_ids: List of item IDs to delete
    
    Returns:
        JSON string with operation result

Inputs: item_ids (required). Returns: result

get_catalog_itemsB
    Get details for multiple catalog items.
    
    Args:
        item_ids: List of item IDs to retrieve
    
    Returns:
        JSON string with item details

Inputs: item_ids (required). Returns: result

search_catalog_itemsA
    Search for items in the Turbify Store catalog.
    Note: This simple search only matches the keyword against item ID, name, or code fields.
    For more advanced search capabilities against other fields, use advanced_search_catalog_items.
    
    Args:
        keyword: Search keyword (matches against ID, name, or code fields only)
        start_index: Starting index for pagination (default: 1)
        end_index: Ending index for pagination (default: 100, max: 1000)
    
    Returns:
        JSON string with search results

Inputs: keyword (required), start_index, end_index. Returns: result

update_itemsC
    Update items in Turbify Merchant Solutions catalog using the Catalog API. TableId and Id cannot be updated.
    HTML included in the request values must be contained within CDATA tags.

    Args:
        items: List of item dictionaries to update. Each item must have:
            - id (str): Unique item ID, this cannot be updated

    Returns:
        JSON string with creation results including success status and any error messages

Inputs: items (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity: advanced_search_catalog_items and search_catalog_items are explicitly differentiated in their descriptions, while create_items, get_catalog_items, update_items, and delete_items form a clean CRUD pattern. The descriptions clearly explain when to use each tool, preventing misselection.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout: advanced_search_catalog_items, create_items, delete_items, get_catalog_items, search_catalog_items, and update_items. The naming is predictable and follows the same structural convention across all six tools.

    Tool Count5/5

    Six tools is well-scoped for a catalog/items management server. The set covers core CRUD operations plus both simple and advanced search capabilities, with each tool earning its place. This is neither too sparse nor bloated for the domain of managing a store catalog.

    Completeness5/5

    The tool surface provides complete CRUD lifecycle coverage for catalog items (create, get, update, delete) plus comprehensive search functionality with both simple and advanced options. There are no obvious gaps or dead ends for agents working with this catalog management domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • TMF620 MCP Server

      oopsyz
      A
      license
      Not graded
      quality
      D
      maintenance
      Allows AI agents to interact with a remote TMF620 Product Catalog Management API, enabling operations like listing, retrieving, and creating catalogs, product offerings, and product specifications.
      3
      MIT

    • mouser-search-mcp

      cmaurer
      A
      license
      Not graded
      quality
      C
      maintenance
      Provides tools to search the Mouser Electronics parts catalog via keyword, part number, and manufacturer queries using the Mouser Search API.
      3
      MIT