npm package: @steven13/ziphq-mcp-server
Description: MCP server for Zip HQ API integration - READ ONLY operations
Latest version: 1.0.0

# Zip HQ MCP Server

> **Unofficial, community-built MCP server for Zip HQ API**
> Not affiliated with or endorsed by Zip HQ. Built by the community for the community.

MCP server for Zip HQ API integration - Phase 1: READ-ONLY operations.

## Features

This MCP server provides read-only access to Zip HQ entities with **16 comprehensive tools**:

- **Requests** - Search and retrieve purchase requests with enhanced filtering
- **Purchase Orders** - Access PO data including line items and vendor info
- **Vendors** - Search and view vendor details, contacts, and metadata
- **Departments** - List and retrieve department/cost center information
- **Users** - Search users and view their roles, permissions, and details
- **Approvals** - Search approval workflows and approval steps
- **Invoices** - Search and retrieve bills/invoices with payment status
- **Subsidiaries** - List legal entities and organizational structures
- **Agreements** - Search contracts and agreements with renewal dates
- **Audit Logs** - Query audit trail events (requires Zip Premier)
- **Comments** - Search comments on requests and invoices

## Available Tools (17 Total)

### Requests
- `zip_search_requests` - Enhanced search with 15+ filters: number, status, type, vendor, department, requester, priority, dates (created/completed/updated), custom attributes
- `zip_get_request` - Get complete details for a specific request by ID

### Purchase Orders
- `zip_search_purchase_orders` - Search POs by vendor, department, status, creation dates
- `zip_get_purchase_order` - Get complete PO details including all line items

### Vendors
- `zip_search_vendors` - Search vendors by name, status (6 status types), subsidiary, department, update dates, with custom attributes
- `zip_get_vendor` - Get complete vendor details including address, contacts, and relationships

### Departments
- `zip_search_departments` - List all departments with sorting
- `zip_get_department` - Get specific department details

### Users
- `zip_search_users` - Search users by email or active/deactivated status
- `zip_get_user` - Get complete user details including roles, permissions, and manager hierarchy

### Approvals
- `zip_search_approvals` - Search approval steps by request, status, node type, due dates, completion dates, assignee

### Invoices
- `zip_search_invoices` - Search bills by status (12 statuses), vendor, department, creation dates
- `zip_get_invoice` - Get complete invoice with line items and payment details

### Subsidiaries
- `zip_search_subsidiaries` - List all legal entities with addresses
- `zip_get_subsidiary` - Get specific subsidiary details

### Agreements
- `zip_search_agreements` - Search contracts by vendor, subsidiary, department with renewal info

### Audit Logs
- `zip_search_audit_logs` - Query audit events by type, creator, date range (requires Zip Premier subscription)

### Comments
- `zip_search_comments` - Search comments on requests or invoices by request_guid or invoice_id

## Installation

### From npm (Recommended)

```bash
npm install -g @steven13/ziphq-mcp-server
```

### From Source

```bash
git clone https://github.com/stevenvo/ziphq-mcp-server.git
cd ziphq-mcp-server
npm install
npm run build
```

## Configuration

Set the `ZIP_API_KEY` environment variable:

```bash
export ZIP_API_KEY=your_zip_api_key_here
```

## Usage

Run the server:

```bash
npm start
```

Or for development with auto-reload:

```bash
npm run dev
```

## Testing

Test with MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## API Details

- **Base URL**: https://api.ziphq.com
- **Authentication**: Zip-Api-Key header
- **Rate Limit**: 150,000 requests per day per API key
- **Pagination**: Uses `page_size` (max 100) and `page_token` parameters

## Response Formats

All tools support two response formats:
- `markdown` (default) - Human-readable formatted text
- `json` - Structured data for programmatic processing

## Notes

- This is Phase 1: READ-ONLY operations only
- All tools are marked with `readOnlyHint: true` and `destructiveHint: false`
- Supports pagination for large result sets
- Includes comprehensive error handling with actionable messages
- Character limit protection prevents oversized responses

## Documentation

Full Zip API documentation: https://developers.ziphq.com/zipapidocs/reference