Metadata-Version: 2.4
Name: ziphq-mcp
Version: 0.1.5
Summary: MCP server for Zip API integration
Project-URL: Homepage, https://github.com/Greenbax/evergreen
Project-URL: Repository, https://github.com/Greenbax/evergreen
Author-email: Hai Nguyen <hai@ziphq.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.11.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Zip MCP Server

An MCP (Model Context Protocol) server for integrating with the Zip API, built with [FastMCP](https://github.com/jlowin/fastmcp).

## Installation

```bash
pip install ziphq-mcp
```

Or with uv:

```bash
uv pip install ziphq-mcp
```

## Usage

### With Claude Code / Claude Desktop

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

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

### Running directly

```bash
# 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

```bash
# 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

```bash
# Build the package
uv build

# Upload to PyPI (requires PyPI credentials)
uv publish
```

## License

MIT
