ziphq-mcp 0.1.0

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

Tool	Description
zip_search_requests	Search for purchase requests with filters (status, priority, requester, vendor, department, dates, etc.)
zip_get_request	Get details of a specific purchase request by ID

zip_search_requests Parameters

Parameter	Type	Description
request_number	string	The request number in Zip
status	int	1=AWAITING_APPROVAL, 2=REJECTED, 3=APPROVED, 4=CANCELED, 5=CLOSED, 6=PAUSED
priority	int	0=Urgent, 1=Normal
requester_id	string	User ID (UUID) of the requester
requester_name	string	Requester name
request_type	string	PURCHASE_REQUEST, SECURITY_REVIEW, VENDOR_ONBOARDING, SOURCING_REQUEST, PO_CHANGE_ORDER
department_name	string	Name of the department
department_id	list[string]	List of department IDs (UUIDs)
vendor_name	string	Name of the vendor
vendor_id	string	ID (UUID) of the vendor
created_after	int	Epoch timestamp (seconds)
created_before	int	Epoch timestamp (seconds)
completed_after	int	Epoch timestamp (seconds)
completed_before	int	Epoch timestamp (seconds)
last_updated_after	int	Epoch timestamp (seconds)
last_updated_before	int	Epoch timestamp (seconds)
include_attributes	bool	Include custom fields in response
sort_by	string	create_time, complete_time, last_updated_time, request_number, status
sort_order	string	asc, desc
page_size	int	Number of results per page
page_token	string	Pagination token for next page

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

Project Structure

zip_mcp/
├── src/
│   ├── __init__.py
│   ├── app.py          # FastMCP instance and configuration
│   ├── server.py       # Main entry point
│   └── tools/
│       ├── __init__.py
│       └── requests.py # Purchase request tools
├── pyproject.toml
└── README.md

Development

# Navigate to the zip_mcp directory
cd zip_mcp

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# 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