ucp

The ucp-mcp-server provides a Python-based MCP toolset that exposes UCP (Universal Commerce Protocol) shopping capabilities to AI assistants. It bridges the gap between AI copilots and UCP-enabled merchants by offering structured, tool-like endpoints such as ucp_discover, ucp_checkout_create, ucp_checkout_update, ucp_checkout_set_fulfillment, and ucp_checkout_complete. This lets Claude, Cursor, or any MCP-compatible AI call into a merchant’s capabilities in a safe, typed manner without scraping or browser automation. You can run the server locally and point your AI assistant at the exposed MCP tools to perform discovery, create and manage checkouts, apply discounts, set fulfillment, and finalize payments.

To use it with your AI assistant, register the MCP server under a name like ucp-shopping in your agent’s MCP configuration. Then call the available tools in sequence to discover merchant capabilities, create a checkout, apply discounts if needed, set fulfillment, and complete the purchase. Each tool returns structured data (e.g., checkout_id, totals, line items, and fulfillment details) which your AI can consume to drive the conversation and decisions with the user.

Typical flow: discover a merchant with ucp_discover, create a checkout with ucp_checkout_create including items and buyer info, optionally apply a discount with ucp_checkout_update, set shipping with ucp_checkout_set_fulfillment, and finally complete the order with ucp_checkout_complete using a chosen payment handler.

Prerequisites:

• Python 3.8+ installed on your system
• Access to pip (included with Python)
• Optional: uv (uvicorn) for development/testing if you want to follow the example commands (not strictly required for installation)

Install the MCP server package from PyPI:

pip install ucp-mcp-server

Or install and run via uv (recommended for development):

uv pip install ucp-mcp-server

Verify installation by running the server directly (see Run Directly in the README for details):

# As a module
python -m ucp_mcp_server

# Or via the entry point (if installed as a console script)
ucp-mcp-server

Optionally, for development workflow using uv:

# Install development dependencies if you clone the repo
git clone https://github.com/nguthrie/ucp-mcp-server.git
cd ucp-mcp-server
uv sync --extra dev

# Run tests or start the server
uv run pytest -v

Environment and configuration tips:

• If your deployment requires a specific UCP merchant URL, configure it in your environment or in the tool calls where the merchant_url is provided.
• Ensure network access to the UCP-enabled merchant endpoints and that any required API keys or payment credentials are securely provided at runtime (do not hard-code credentials).
• When testing, use the integration tests as a guide to expected responses (checkout IDs, totals, and order IDs).
• The server exposes standard MCP tools; ensure your AI agent uses the correct argument shapes for each tool (see Tools Reference in the README for exact input/output formats).
• If you switch from a local run to a production deployment, consider containerization with Docker or platform-specific deployment (e.g., uvx in Python environments) and set up appropriate environment variables for merchant URLs and credentials.