ziphq-mcp 0.1.5

MCP server for Zip API integration

Zip MCP Server

An MCP (Model Context Protocol) server for integrating with the Zip API, built with FastMCP.

Installation

pip install ziphq-mcp

Or with uv:

uv pip install ziphq-mcp

Usage

With Claude Code / Claude Desktop

Add to your MCP configuration (e.g., ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zip": {
      "command": "uv",
      "args": ["run", "--with", "ziphq-mcp", "ziphq-mcp"],
      "env": {
        "ZIP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Running directly

# Set the API key via environment variable
export ZIP_API_KEY="your-api-key-here"

# Run with uv (recommended)
uv run --with ziphq-mcp ziphq-mcp

# Or if installed globally
ziphq-mcp

Available Tools (131)

60 read tools + 71 write tools across 9 domains. By default only read tools are registered. Set ZIP_MCP_MODE=readwrite to enable write tools.

Write tools accept a data parameter as a JSON string.

Agreements (6)

Tool	Method	Description
zip_search_agreements	GET	Search agreements with vendor, subsidiary, department filters
zip_get_agreement	GET	Get a single agreement by ID
zip_create_agreement	POST	Create a new agreement
zip_update_agreement	PATCH	Update an existing agreement
zip_schedule_agreement_renewal	PATCH	Schedule a renewal for an agreement
zip_cancel_agreement_renewal	PATCH	Cancel a scheduled renewal

Procurement (26)

Tool	Method	Description
zip_search_purchase_orders	GET	Search purchase orders
zip_get_purchase_order	GET	Get a single purchase order by ID
zip_create_purchase_order	POST	Create a new purchase order
zip_update_purchase_order	PATCH	Update an existing purchase order
zip_add_purchase_order_line_items	POST	Add line items to a purchase order
zip_search_requests	GET	Search purchase requests
zip_get_request	GET	Get a single purchase request by ID
zip_update_request	PATCH	Update an existing request
zip_update_request_line_items	PATCH	Update line items on a request
zip_update_request_sourcing_vendors	PATCH	Update sourcing vendors on a request
zip_search_invoices	GET	Search invoices
zip_get_invoice	GET	Get a single invoice by ID
zip_create_invoice	POST	Create a new invoice
zip_update_invoice	PATCH	Update an existing invoice
zip_add_invoice_line_items	POST	Add line items to an invoice
zip_update_invoice_line_item	PATCH	Update a specific invoice line item
zip_update_invoice_paid_status	PATCH	Update the paid status of an invoice
zip_send_invoice_for_approval	PATCH	Send an invoice for approval
zip_search_line_items	GET	Search line items for an invoice
zip_search_approvals	GET	Search approval nodes
zip_search_comments	GET	Search comments for a request
zip_create_comment	POST	Create a comment on a request
zip_delete_comment	DELETE	Delete a comment
zip_search_change_orders	GET	Search change orders
zip_get_change_order	GET	Get a single change order by ID
zip_get_request_questionnaire_responses	GET	Get questionnaire responses for a request

Finance (10)

Tool	Method	Description
zip_search_item_receipts	GET	Search item receipts
zip_get_item_receipt	GET	Get a single item receipt by ID
zip_search_payouts	GET	Search payouts
zip_get_payout	GET	Get a single payout by ID
zip_get_payment_method	GET	Get a single payment method by ID
zip_get_cash_back	GET	Get a single cash back record by ID
zip_get_top_up	GET	Get a single top-up record by ID
zip_get_transaction	GET	Get a single transaction by ID
zip_update_payment_method	PATCH	Update a payment method
zip_update_virtual_card	PATCH	Update a virtual card

Vendors (10)

Tool	Method	Description
zip_search_vendors	GET	Search vendors
zip_get_vendor	GET	Get a single vendor by ID
zip_upsert_vendor	PUT	Create or update a vendor (upsert)
zip_update_vendor	PATCH	Update an existing vendor
zip_delete_vendor	DELETE	Delete a vendor
zip_search_vendor_credits	GET	Search vendor credits
zip_get_vendor_credit	GET	Get a single vendor credit by ID
zip_create_vendor_contact	POST	Create a vendor contact
zip_create_address	POST	Create an address
zip_update_address	PATCH	Update an address

Users (7)

Tool	Method	Description
zip_search_users	GET	Search users
zip_get_user	GET	Get a single user by ID
zip_create_user	POST	Create a new user
zip_update_user	PATCH	Update an existing user
zip_delete_user	DELETE	Deactivate (delete) a user
zip_search_user_groups	GET	Search user groups
zip_get_user_group	GET	Get a single user group by ID

Reference Data (50)

Tool	Method	Description
zip_search_departments	GET	Search departments
zip_create_department	POST	Create a department
zip_update_department	PATCH	Update a department
zip_delete_department	DELETE	Delete a department
zip_search_subsidiaries	GET	Search subsidiaries
zip_create_subsidiary	POST	Create a subsidiary
zip_update_subsidiary	PATCH	Update a subsidiary
zip_delete_subsidiary	DELETE	Delete a subsidiary
zip_search_roles	GET	Search roles
zip_create_role	POST	Create a role
zip_update_role	PATCH	Update a role
zip_delete_role	DELETE	Delete a role
zip_search_gl_codes	GET	Search GL codes
zip_create_gl_code	POST	Create a GL code
zip_update_gl_code	PATCH	Update a GL code
zip_search_tax_codes	GET	Search tax codes
zip_create_tax_code	POST	Create a tax code
zip_update_tax_code	PATCH	Update a tax code
zip_delete_tax_code	DELETE	Delete a tax code
zip_search_currencies	GET	Search currencies
zip_upsert_currencies	PUT	Create or update currencies
zip_search_lookups	GET	Search custom lookup tables
zip_create_lookup	POST	Create a lookup table
zip_update_lookup	PATCH	Update a lookup table
zip_delete_lookup	DELETE	Delete a lookup table
zip_search_lookup_options	GET	Search lookup options
zip_get_lookup_option	GET	Get a single lookup option by ID
zip_create_lookup_option	POST	Create a lookup option
zip_update_lookup_option	PATCH	Update a lookup option
zip_delete_lookup_option	DELETE	Delete a lookup option
zip_search_budgets	GET	Search budgets
zip_upsert_budgets	PUT	Create or update budgets
zip_upsert_budget_actuals	PUT	Create or update budget actuals
zip_search_expense_categories	GET	Search expense categories
zip_create_expense_category	POST	Create an expense category
zip_update_expense_category	PATCH	Update an expense category
zip_delete_expense_category	DELETE	Delete an expense category
zip_search_locations	GET	Search locations
zip_create_location	POST	Create a location
zip_update_location	PATCH	Update a location
zip_delete_location	DELETE	Delete a location
zip_search_payment_terms	GET	Search payment terms
zip_get_payment_term	GET	Get a single payment term by ID
zip_search_purchase_categories	GET	Search purchase categories
zip_search_item_accounts	GET	Search item accounts
zip_get_item_account	GET	Get a single item account by ID
zip_create_item_account	POST	Create an item account
zip_search_amortization_schedules	GET	Search amortization schedules
zip_get_amortization_schedule	GET	Get a single amortization schedule by ID
zip_create_saving_line_item	POST	Create a saving line item

Audit Trail (1)

Tool	Method	Description
zip_search_event_logs	GET	Search audit trail event logs

Workflows (11)

Tool	Method	Description
zip_list_workflows	GET	List all request workflows
zip_get_workflow_intake_form	GET	Get a workflow's intake form
zip_get_workflow_conditions	GET	Get a workflow's conditions
zip_get_queue	GET	Get a single queue by ID
zip_create_queue	POST	Create a new queue
zip_create_subqueue	POST	Create a subqueue under an existing queue
zip_update_queue	PATCH	Update an existing queue
zip_delete_queue	DELETE	Delete a queue
zip_get_engagement	GET	Get a single engagement by ID
zip_get_engagement_schema	GET	Get the engagement schema definition
zip_upsert_engagement	PUT	Create or update an engagement

Catalog (10)

Tool	Method	Description
zip_search_catalog	GET	Search the product catalog
zip_get_products	GET	Get products by GUIDs
zip_create_product	POST	Create a new product
zip_update_product	PATCH	Update a product
zip_get_vendor_items	GET	Get vendor items by GUIDs
zip_create_vendor_item	POST	Create a new vendor item
zip_update_vendor_item	PATCH	Update a vendor item
zip_get_vendor_item_groups	GET	Get vendor item groups by GUIDs
zip_create_vendor_item_group	POST	Create a new vendor item group
zip_update_vendor_item_group	PATCH	Update a vendor item group

Configuration

The server requires a Zip API key. You can provide it in two ways:

1. Environment variable: Set ZIP_API_KEY
2. MCP configuration: Pass it via the env section in your MCP config

Variable	Required	Default	Description
ZIP_API_KEY	Yes	—	API key for authentication (generate in Zip > Settings > API Keys)
ZIP_MCP_MODE	No	readonly	readonly for read tools only, readwrite to enable write tools

Project Structure

zip_mcp/
├── src/
│   ├── __init__.py
│   ├── app.py              # FastMCP instance and configuration
│   ├── api_client.py       # HTTP client for Zip API (GET/POST/PATCH/PUT/DELETE)
│   ├── server.py           # Main entry point
│   └── tools/
│       ├── __init__.py     # Tool registration and shared annotations
│       ├── agreements.py   # Agreement tools (6)
│       ├── audit_trail.py  # Event log tools (1)
│       ├── catalog.py      # Catalog/product tools (10)
│       ├── finance.py      # Item receipts, payouts, payment methods, etc. (10)
│       ├── procurement.py  # POs, requests, invoices, approvals, etc. (26)
│       ├── reference_data.py # Departments, GL codes, payment terms, etc. (50)
│       ├── users.py        # User and user group tools (7)
│       ├── vendors.py      # Vendor and vendor credit tools (10)
│       └── workflows.py    # Workflows, queues, engagements (11)
├── pyproject.toml
└── README.md

Development

# Navigate to the zip_mcp directory
cd zip_mcp

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run python -m pytest tests/ -v

# Format code
uv run ruff format .
uv run ruff check --fix .

Publishing to PyPI

# Build the package
uv build

# Upload to PyPI (requires PyPI credentials)
uv publish

License

MIT