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

Installation

1. Clone this repository:

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

2. 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