Square Model Context Protocol Server

https://github.com/square/square-mcp-server
Admin
A Model Context Protocol server that enables AI assistants to interact with Square's Connect API for...
Tokens:41,678
Snippets:504
Trust Score:9.4
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Interactive installation output

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Example output from running the install command.

```text
🚀 Starting Square MCP Server installation...
🔑 Enter your Square ACCESS_TOKEN: sq_atp-...
🏝️  Use Square sandbox environment? (y/N): y
🏝️  Using sandbox environment
Updating Claude configuration...
Updated Claude configuration at ~/.config/claude/config.json
Updating Goose configuration...
Updated Goose configuration at ~/.config/goose/config.yaml
✨ Installation complete!
```

--------------------------------

### install

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Performs an interactive setup to configure Claude Desktop and Goose with the MCP server.

```APIDOC
## install

### Description
Interactive setup that configures Claude Desktop and Goose with the MCP server.

### Usage
```bash
npx square-mcp-server install
```

### Prompts
- **Square ACCESS_TOKEN**
- **Sandbox mode preference**
```

--------------------------------

### Install and configure the MCP server

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Runs an interactive setup to configure Claude Desktop and Goose. Updates configuration files and prompts for credentials and sandbox preferences.

```bash
npx square-mcp-server install
```

--------------------------------

### start

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Starts the MCP server and connects to stdio transport. Requires the ACCESS_TOKEN environment variable.

```APIDOC
## start

### Description
Starts the MCP server and connects to stdio transport.

### Usage
```bash
npx square-mcp-server start
```

### Requirements
- **ACCESS_TOKEN** (env) - Required - Environment variable for authentication.
```

--------------------------------

### Get order usage example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

Example of retrieving an order and accessing its properties from the response.

```typescript
const response = await make_api_request({
  service: "orders",
  method: "get",
  request: {
    order_id: "CAZ5W4GQVEHQEVYF7PZNNOA"
  }
});

const order = JSON.parse(response.content[0].text).order;
console.log(`Order ${order.id}`);
console.log(`Total: ${order.total_money.amount / 100}`);
console.log(`State: ${order.state}`);
```

--------------------------------

### Usage Examples for get_service_info

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Examples demonstrating how to retrieve and process service methods for different services.

```typescript
const response = await get_service_info({
  service: "catalog"
});

const methods = JSON.parse(response.content[0].text);
// Output:
// {
//   "list": { "description": "List catalog objects..." },
//   "getObject": { "description": "Get a single object..." },
//   "create": { "description": "Create or update..." },
//   ...
// }
```

```typescript
const response = await get_service_info({
  service: "customers"
});

const methods = JSON.parse(response.content[0].text);
console.log(Object.keys(methods)); // ["list", "create", "get", "update", ...]
```

```typescript
const response = await get_service_info({
  service: "payments"
});

if (!response.isError) {
  const methods = JSON.parse(response.content[0].text);
  Object.entries(methods).forEach(([name, info]) => {
    console.log(`${name}: ${info.description}`);
  });
}
```

--------------------------------

### Start the server

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Execute the server using npx.

```bash
npx square-mcp-server start
```

--------------------------------

### Create Customer Usage Examples

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Examples showing how to create a customer with full details and a minimal customer using only an email address.

```typescript
// Create customer with full details
const response = await make_api_request({
  service: "customers",
  method: "create",
  request: {
    given_name: "John",
    family_name: "Doe",
    email_address: "john@example.com",
    phone_number: "+1-555-0123",
    address: {
      address_line_1: "123 Main St",
      address_line_2: "Apt 4",
      administrative_district_level_1: "CA",
      postal_code: "94102",
      country: "US"
    },
    note: "VIP customer",
    idempotency_key: "new-cust-001"
  }
});

const customer = JSON.parse(response.content[0].text).customer;
console.log(`Created: ${customer.id}`);

// Minimal customer (just email)
const minimal = await make_api_request({
  service: "customers",
  method: "create",
  request: {
    email_address: "jane@example.com"
  }
});
```

--------------------------------

### Get Payment Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/004-payments-service.md

Example of retrieving a payment by ID and accessing its properties from the response.

```typescript
const response = await make_api_request({
  service: "payments",
  method: "get",
  request: {
    payment_id: "payment_abc123"
  }
});

const payment = JSON.parse(response.content[0].text).payment;
console.log(`Status: ${payment.status}`);
console.log(`Amount: ${payment.amount_money.amount}`);
console.log(`Created: ${payment.created_at}`);
if (payment.receipt) {
  console.log(`Receipt: ${payment.receipt.receipt_url}`);
}
```

--------------------------------

### Retrieve Invoice Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Example of calling the get method via the API request helper.

```typescript
const response = await make_api_request({
  service: "invoices",
  method: "get",
  request: {
    invoice_id: "inv_abc123"
  }
});

const invoice = JSON.parse(response.content[0].text).invoice;
console.log(`Invoice #${invoice.invoice_number}`);
console.log(`Status: ${invoice.state}`);
console.log(`Total: ${invoice.total_money.amount / 100}`);
```

--------------------------------

### Bulk create customers usage example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Example of creating multiple customers and parsing the response map.

```typescript
const response = await make_api_request({
  service: "customers",
  method: "bulkCreate",
  request: {
    customers: {
      "cust-001": {
        given_name: "Alice",
        email_address: "alice@example.com"
      },
      "cust-002": {
        given_name: "Bob",
        phone_number: "+1-555-1234"
      }
    }
  }
});

const results = JSON.parse(response.content[0].text);
Object.entries(results.responses).forEach(([key, resp]) => {
  if (resp.customer) {
    console.log(`${key} -> ${resp.customer.id}`);
  } else if (resp.errors) {
    console.log(`${key} failed: ${resp.errors[0].detail}`);
  }
});
```

--------------------------------

### Get Order Creation Parameters

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Example of iterating through properties to identify array types and requirements.

```typescript
const response = await get_type_info({
  service: "orders",
  method: "create"
});

const types = JSON.parse(response.content[0].text);
types[0].properties.forEach(prop => {
  if (prop.arrayType) {
    console.log(`${prop.name}: Array of ${prop.arrayType}`);
  } else {
    console.log(`${prop.name}: ${prop.type}${prop.required ? ' (required)' : ''}`);
  }
});
```

--------------------------------

### Get Customer Creation Parameters

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Example of filtering for required properties in the customer creation schema.

```typescript
const response = await get_type_info({
  service: "customers",
  method: "create"
});

const types = JSON.parse(response.content[0].text);
const schema = types[0];  // CreateCustomerRequest

// Find required properties
const required = schema.properties.filter(p => p.required);
console.log(required.map(p => `${p.name} (${p.type})`));
// Output:
// May include: given_name, family_name, company_name, email_address, phone_number
```

--------------------------------

### Create Payment Usage Examples

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/004-payments-service.md

Examples demonstrating basic payment processing, payments with tips and customer linking, and authorization holds using delayed capture.

```typescript
// Basic payment with card token
const response = await make_api_request({
  service: "payments",
  method: "create",
  request: {
    source_id: "ccof:cbcc2514-a1db-497d-81a7-9b0c01ad02ad",
    amount_money: {
      amount: 1000,  // $10.00 USD
      currency: "USD"
    },
    idempotency_key: "payment-123-abc",
    autocomplete: true
  }
});

const payment = JSON.parse(response.content[0].text).payment;
console.log(`Payment ID: ${payment.id}`);
console.log(`Status: ${payment.status}`);

// Payment with tip and customer link
const fullPayment = await make_api_request({
  service: "payments",
  method: "create",
  request: {
    source_id: "ccof:...",
    customer_id: "CUST_123",
    amount_money: {
      amount: 5000,
      currency: "USD"
    },
    tip_money: {
      amount: 500,
      currency: "USD"
    },
    receipt: {
      email: "customer@example.com"
    },
    idempotency_key: "order-456-def",
    autocomplete: true
  }
});

// Delayed capture (authorization hold)
const authorizedOnly = await make_api_request({
  service: "payments",
  method: "create",
  request: {
    source_id: "ccof:...",
    amount_money: { amount: 10000, currency: "USD" },
    delay_capture: true,
    idempotency_key: "auth-789-ghi"
  }
});
```

--------------------------------

### Get Catalog List Parameters

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Example of retrieving and parsing the schema for the catalog list method.

```typescript
const response = await get_type_info({
  service: "catalog",
  method: "list"
});

const types = JSON.parse(response.content[0].text);
// Returns:
// [
//   {
//     name: "ListCatalogRequest",
//     properties: [
//       { name: "cursor", type: "string", required: false, ... },
//       { name: "types", type: "string", required: false, ... },
//       { name: "limit", type: "integer", required: false, ... }
//     ]
//   }
// ]
```

--------------------------------

### Generate Goose installation URL

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Outputs a URL for installing the Goose integration.

```bash
npx square-mcp-server get-goose-url
```

--------------------------------

### Create Order Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

Example of calling the create method via the API request wrapper, including line items, discounts, and taxes.

```typescript
const response = await make_api_request({
  service: "orders",
  method: "create",
  request: {
    idempotency_key: "order-2024-001",
    order: {
      line_items: [
        {
          name: "Cheese Pizza",
          quantity: "1",
          gross_sales_money: {
            amount: 1000,
            currency: "USD"
          }
        },
        {
          name: "Breadsticks",
          quantity: "2",
          gross_sales_money: {
            amount: 400,
            currency: "USD"
          }
        }
      ],
      discounts: [
        {
          name: "Holiday Promo",
          type: "FIXED_PERCENTAGE",
          percentage: "10"
        }
      ],
      taxes: [
        {
          name: "Sales Tax",
          percentage: "8.5"
        }
      ]
    },
    customer_id: "CUST_123"
  }
});

const order = JSON.parse(response.content[0].text).order;
console.log(`Created order: ${order.id}`);
```

--------------------------------

### Start the Square MCP Server

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/README.md

Configure environment variables and launch the server using npx.

```bash
export ACCESS_TOKEN="sq_atp-..."
export SANDBOX=true
npx square-mcp-server start
```

--------------------------------

### Install and Configure Square MCP for Goose

Source: https://github.com/square/square-mcp-server/blob/main/README.md

Use these commands to automatically install the server or retrieve the URL for manual Goose configuration.

```bash
# Automatic installation
npx square-mcp-server install

# Get URL for manual installation
npx square-mcp-server get-goose-url
```

--------------------------------

### Get Catalog Object Usage

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Examples of retrieving catalog objects, including variations, category paths, and related objects.

```typescript
// Get item with all variations
const response = await make_api_request({
  service: "catalog",
  method: "getObject",
  request: {
    object_id: "ITEM_1234567890ABC"
  }
});

const item = JSON.parse(response.content[0].text).object;
console.log(`Item: ${item.item_data.name}`);
console.log(`Variations: ${item.item_data.variations?.length || 0}`);

// Get category with path to root
const categoryResponse = await make_api_request({
  service: "catalog",
  method: "getObject",
  request: {
    object_id: "CATEGORY_ABC123",
    include_category_path_to_root: true
  }
});

// Get with related objects
const withRelated = await make_api_request({
  service: "catalog",
  method: "getObject",
  request: {
    object_id: "ITEM_123",
    include_related_objects: true
  }
});
```

--------------------------------

### Create Invoice Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Example of calling the create method via the API request helper.

```typescript
const response = await make_api_request({
  service: "invoices",
  method: "create",
  request: {
    invoice: {
      invoice_number: "INV-001",
      order_id: "ORDER_123",
      customer_id: "CUST_456",
      primary_recipient: {
        customer_id: "CUST_456"
      },
      payment_requests: [
        {
          request_type: "BALANCE",
          due_date: "2024-02-20",
          reminders: [
            {
              reminder_type: "BEFORE",
              relative_timing: "1 day"
            }
          ]
        }
      ],
      description: "Invoice for services",
      accepted_payment_methods: {
        card: true,
        square_gift_card: true,
        bank_account: false
      }
    }
  }
});

const invoice = JSON.parse(response.content[0].text).invoice;
console.log(`Created: ${invoice.id}`);
```

--------------------------------

### List Invoices Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Example of calling the list method with sorting and limit parameters.

```typescript
const response = await make_api_request({
  service: "invoices",
  method: "list",
  request: {
    limit: 50,
    sort_field: "INVOICE_SORT_DATE",
    sort_order: "DESC"
  }
});

const data = JSON.parse(response.content[0].text);
console.log(`Found ${data.invoices?.length || 0} invoices`);
```

--------------------------------

### Create Catalog Image Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Example of calling the createImage method via the MCP server API.

```typescript
// This typically requires special handling for file uploads
// The MCP server accepts the image as part of the request

const response = await make_api_request({
  service: "catalog",
  method: "createImage",
  request: {
    image_data: {
      // Image metadata
    },
    object_id: "ITEM_123"  // Optional: attach to item
  }
});
```

--------------------------------

### Search Invoices Usage Examples

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Examples of searching invoices by customer ID or by invoice state.

```typescript
// Search by customer
const response = await make_api_request({
  service: "invoices",
  method: "search",
  request: {
    query: {
      filter: {
        customer_ids: ["CUST_123"]
      }
    }
  }
});

// Search by state
const unpaid = await make_api_request({
  service: "invoices",
  method: "search",
  request: {
    query: {
      filter: {
        invoice_states: ["SCHEDULED", "PUBLISHED"]
      }
    }
  }
});
```

--------------------------------

### Development workflow commands

Source: https://github.com/square/square-mcp-server/blob/main/README.md

Standard commands for installing dependencies and running the server in development mode.

```bash
npm install
npm run watch
node dist/index.js start
```

--------------------------------

### Search Catalog Objects Usage Examples

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Examples demonstrating text-based search, structured query filtering, and including deleted items in the results.

```typescript
// Search for items by name
const response = await make_api_request({
  service: "catalog",
  method: "searchObjects",
  request: {
    text_query: "pizza",
    limit: 25
  }
});

const results = JSON.parse(response.content[0].text);
console.log(`Found ${results.objects?.length || 0} items matching "pizza"`);

// Search with query filters
const advancedSearch = await make_api_request({
  service: "catalog",
  method: "searchObjects",
  request: {
    query: {
      exact_query: {
        attribute_name: "name",
        attribute_value: "Pepperoni Pizza"
      }
    }
  }
});

// Include deleted items
const withDeleted = await make_api_request({
  service: "catalog",
  method: "searchObjects",
  request: {
    text_query: "old item",
    include_deleted_objects: true
  }
});
```

--------------------------------

### Configure Development Environment

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Sets the server to sandbox mode using environment variables before starting.

```bash
export ACCESS_TOKEN="sq_atp-..."
export SANDBOX=true
export SQUARE_VERSION="2025-04-16"
npx square-mcp-server start
```

--------------------------------

### List Customers Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Demonstrates fetching a list of customers with pagination and sorting parameters.

```typescript
// Get first 50 customers
const response = await make_api_request({
  service: "customers",
  method: "list",
  request: {
    limit: 50,
    sort_field: "CREATED_AT",
    sort_order: "DESC",
    count: true
  }
});

const data = JSON.parse(response.content[0].text);
console.log(`Total customers: ${data.pagination?.total}`);
console.log(`Retrieved: ${data.customers?.length || 0}`);

// Paginate
if (data.pagination?.cursor) {
  const page2 = await make_api_request({
    service: "customers",
    method: "list",
    request: {
      cursor: data.pagination.cursor,
      limit: 50
    }
  });
}
```

--------------------------------

### Create Customer via make_api_request

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Example of creating a new customer record.

```typescript
const response = await make_api_request({
  service: "customers",
  method: "create",
  request: {
    given_name: "John",
    family_name: "Doe",
    email_address: "john@example.com"
  }
});

if (!response.isError) {
  const customer = JSON.parse(response.content[0].text);
  console.log(customer.customer.id);
}
```

--------------------------------

### Start Square MCP Server

Source: https://github.com/square/square-mcp-server/blob/main/README.md

Commands to initialize the Square MCP server locally with various configuration options.

```bash
# Basic startup
npx square-mcp-server start

# With environment configuration
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start

# local runs
npx /path/to/project/square-mcp-server
```

--------------------------------

### List Payments Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/004-payments-service.md

Example of listing payments with filtering parameters and processing the JSON response.

```typescript
// Get recent payments
const response = await make_api_request({
  service: "payments",
  method: "list",
  request: {
    limit: 50,
    sort_order: "DESC",
    begin_time: "2024-01-01T00:00:00Z",
    end_time: "2024-01-31T23:59:59Z"
  }
});

const data = JSON.parse(response.content[0].text);
console.log(`Found ${data.payments?.length || 0} payments`);

data.payments?.forEach(payment => {
  console.log(`${payment.id}: ${payment.amount_money.amount} ${payment.amount_money.currency} - ${payment.status}`);
});
```

--------------------------------

### Bulk Retrieve Customers Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Demonstrates how to call bulkGet and process the returned customer list.

```typescript
const response = await make_api_request({
  service: "customers",
  method: "bulkGet",
  request: {
    customer_ids: ["CUST_001", "CUST_002"]
  }
});

const results = JSON.parse(response.content[0].text);
results.customers?.forEach(customer => {
  console.log(`${customer.id}: ${customer.given_name}`);
});
```

--------------------------------

### Configure Production Environment

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Sets the server to production mode using environment variables before starting.

```bash
export ACCESS_TOKEN="sq_atp-..."
export PRODUCTION=true
export SQUARE_VERSION="2025-04-16"
npx square-mcp-server start
```

--------------------------------

### Invoice workflow example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Demonstrates the full lifecycle of an invoice from creation to publishing and status retrieval.

```typescript
// 1. Create draft invoice
const createResp = await make_api_request({
  service: "invoices",
  method: "create",
  request: {
    invoice: {
      invoice_number: "INV-2024-001",
      customer_id: "CUST_123",
      primary_recipient: { customer_id: "CUST_123" },
      payment_requests: [
        {
          request_type: "BALANCE",
          due_date: "2024-03-01"
        }
      ]
    }
  }
});

const invoice = JSON.parse(createResp.content[0].text).invoice;

// 2. Update if needed
await make_api_request({
  service: "invoices",
  method: "update",
  request: {
    invoice_id: invoice.id,
    invoice: { description: "Service invoice" }
  }
});

// 3. Publish
const publishResp = await make_api_request({
  service: "invoices",
  method: "publish",
  request: {
    invoice_id: invoice.id,
    idempotency_key: "publish-001",
    version: 0
  }
});

const published = JSON.parse(publishResp.content[0].text).invoice;
console.log(`Invoice published: ${published.invoice_url}`);

// 4. Check payment status later
const statusResp = await make_api_request({
  service: "invoices",
  method: "get",
  request: { invoice_id: invoice.id }
});

const current = JSON.parse(statusResp.content[0].text).invoice;
console.log(`Current state: ${current.state}`);
```

--------------------------------

### Search Customers Usage Examples

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Demonstrates searching by name, email address, and creation date using the make_api_request helper.

```typescript
// Search by name
const response = await make_api_request({
  service: "customers",
  method: "search",
  request: {
    query: {
      text_filter: "John Smith"
    },
    limit: 25
  }
});

const results = JSON.parse(response.content[0].text);
console.log(`Found: ${results.customers?.length || 0}`);

// Search with multiple filters
const advanced = await make_api_request({
  service: "customers",
  method: "search",
  request: {
    query: {
      filter: {
        email_address: {
          exact: "john@example.com"
        }
      }
    }
  }
});

// Search created after date
const recent = await make_api_request({
  service: "customers",
  method: "search",
  request: {
    query: {
      filter: {
        created_at: {
          start_at: "2024-01-01T00:00:00Z"
        }
      }
    }
  }
});
```

--------------------------------

### List orders usage example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

Example of calling the list method with time-based filtering and a result limit.

```typescript
const response = await make_api_request({
  service: "orders",
  method: "list",
  request: {
    limit: 50,
    begin_time: "2024-01-01T00:00:00Z",
    end_time: "2024-01-31T23:59:59Z"
  }
});

const data = JSON.parse(response.content[0].text);
console.log(`Found ${data.orders?.length || 0} orders`);
```

--------------------------------

### List Catalog Objects Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Demonstrates retrieving items and handling pagination using the make_api_request helper.

```typescript
// Get all items
const response = await make_api_request({
  service: "catalog",
  method: "list",
  request: {
    types: "ITEM,ITEM_VARIATION",
    limit: 100
  }
});

const data = JSON.parse(response.content[0].text);
console.log(`Found ${data.objects?.length || 0} items`);

// Paginate through results
if (data.pagination?.cursor) {
  const nextPage = await make_api_request({
    service: "catalog",
    method: "list",
    request: {
      types: "ITEM",
      cursor: data.pagination.cursor
    }
  });
}
```

--------------------------------

### RFC 3339 Timestamp Examples

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/004-types-reference.md

Examples of valid timestamp formats including UTC and timezone-offset variants.

```text
2024-01-20T14:30:00Z          (UTC)
2024-01-20T14:30:00-08:00     (With timezone)
```

--------------------------------

### Update Invoice Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Example of calling the update method to modify invoice fields.

```typescript
const response = await make_api_request({
  service: "invoices",
  method: "update",
  request: {
    invoice_id: "inv_abc123",
    invoice: {
      description: "Updated description",
      due_date: "2024-03-01"
    }
  }
});
```

--------------------------------

### Delete customer usage example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Example of calling the delete method via the API request helper.

```typescript
const response = await make_api_request({
  service: "customers",
  method: "delete",
  request: {
    customer_id: "JDPSH23EIKE"
  }
});

if (!response.isError) {
  console.log("Customer deleted");
}
```

--------------------------------

### get-goose-url

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Generates a Goose installation URL.

```APIDOC
## get-goose-url

### Description
Generates a Goose installation URL.

### Usage
```bash
npx square-mcp-server get-goose-url
```
```

--------------------------------

### Discount JSON Representation

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/004-types-reference.md

Example of a fixed percentage discount applied to an order.

```json
{
  "name": "Employee Discount",
  "type": "FIXED_PERCENTAGE",
  "percentage": "10"
}
```

--------------------------------

### Generate Goose installation URL

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

The output format for the get-goose-url command.

```text
goose://extension?cmd=npx&arg=square-mcp-server&arg=start&id=mcp_square_api&name=Square%20MCP%20Server&description=Square%20API%20MCP%20Server
```

--------------------------------

### List Catalog Items via make_api_request

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Example of retrieving catalog items using the list method.

```typescript
const response = await make_api_request({
  service: "catalog",
  method: "list",
  request: {
    types: "ITEM",
    limit: 100
  }
});

if (!response.isError) {
  console.log(JSON.parse(response.content[0].text));
}
```

--------------------------------

### Create Location TypeScript Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/006-locations-service.md

Creates a new location with specified address, phone number, and business hours.

```typescript
const response = await make_api_request({
  service: "locations",
  method: "create",
  request: {
    location: {
      name: "Downtown Store",
      address: {
        address_line_1: "123 Main St",
        address_line_2: "Suite 100",
        administrative_district_level_1: "CA",
        postal_code: "94102",
        country: "US"
      },
      phone_number: "+1-555-0123",
      business_hours: [
        {
          day_of_week: "MON",
          periods: [
            {
              start_local_time: "09:00",
              end_local_time: "17:00"
            }
          ]
        }
      ]
    }
  }
});

const location = JSON.parse(response.content[0].text).location;
console.log(`Created: ${location.id}`);
```

--------------------------------

### Upsert Catalog Object Usage Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Demonstrates creating a new item and updating an existing item using the make_api_request helper.

```typescript
// Create new item
const createResponse = await make_api_request({
  service: "catalog",
  method: "upsertObject",
  request: {
    idempotency_key: "new-item-001",
    object: {
      type: "ITEM",
      id: "#NEW_ITEM",
      item_data: {
        name: "Cheese Pizza",
        description: "Fresh mozzarella and tomato sauce",
        variations: [
          {
            type: "ITEM_VARIATION",
            id: "#VARIATION_SMALL",
            item_variation_data: {
              name: "Small",
              pricing_type: "FIXED_PRICING",
              price_money: {
                amount: 800,  // $8.00
                currency: "USD"
              }
            }
          }
        ]
      }
    }
  }
});

const result = JSON.parse(createResponse.content[0].text);
console.log(`Created item: ${result.id_mappings[0].client_object_id}`);

// Update existing item
const updateResponse = await make_api_request({
  service: "catalog",
  method: "upsertObject",
  request: {
    idempotency_key: "update-item-001",
    object: {
      type: "ITEM",
      id: "ITEM_EXISTING_ID",
      item_data: {
        name: "Updated Name",
        description: "Updated description"
      }
    }
  }
});
```

--------------------------------

### Process Payment via make_api_request

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/001-mcp-tools.md

Example of processing a payment with an idempotency key.

```typescript
const response = await make_api_request({
  service: "payments",
  method: "create",
  request: {
    source_id: "ccof:cbcc2514-a1db-497d-81a7-9b0c01ad02ad",
    amount_money: {
      amount: 1000,  // $10.00
      currency: "USD"
    },
    idempotency_key: "ec4e0b0c-c8cd-4d3e-83a9-e5ef4d47a2b7"
  }
});

if (!response.isError) {
  const payment = JSON.parse(response.content[0].text);
  console.log(`Payment: ${payment.payment.id}`);
}
```

--------------------------------

### Minimal Server Startup

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/000-index.md

Basic commands to set the access token and launch the MCP server.

```bash
export ACCESS_TOKEN="sq_atp-..."
npx square-mcp-server start
```

--------------------------------

### GET /v2/catalog/info

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Retrieves catalog metadata, including size limits and current state.

```APIDOC
## GET /v2/catalog/info

### Description
Returns catalog information like size limits and current state.

### Method
GET

### Endpoint
/v2/catalog/info

### Response
#### Success Response (200)
- **Catalog metadata** (object) - Returns catalog information.
```

--------------------------------

### GET /v2/customers/{customer_id}

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

Retrieves a full customer profile including contact information and preferences.

```APIDOC
## GET /v2/customers/{customer_id}

### Description
Gets full customer profile including all contact info and preferences.

### Method
GET

### Endpoint
/v2/customers/{customer_id}

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - ID of customer to retrieve

### Response
#### Success Response (200)
- **Customer** (object) - Customer object with all details.
```

--------------------------------

### Order JSON Representation

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/004-types-reference.md

Example of an order object containing line items and total money.

```json
{
  "id": "CAZ5W4GQVEHQEVYF7PZNNOA",
  "state": "OPEN",
  "line_items": [
    {
      "name": "Pizza",
      "quantity": "1",
      "gross_sales_money": { "amount": 1000, "currency": "USD" }
    }
  ],
  "total_money": { "amount": 1080, "currency": "USD" },
  "created_at": "2024-01-20T14:30:00Z"
}
```

--------------------------------

### Search Catalog Items Usage

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Example of searching for items using custom attribute filters.

```typescript
// Search items with custom attribute filter
const response = await make_api_request({
  service: "catalog",
  method: "searchItems",
  request: {
    text_query: "gluten-free",
    custom_attribute_filters: [
      {
        custom_attribute_definition_id: "attr-123",
        key: "dietary_restriction",
        string_filter: {
          exact: "gluten-free"
        }
      }
    ]
  }
});
```

--------------------------------

### GET /v2/catalog/list

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Retrieves a list of catalog objects in batches, supporting filtering by type and pagination.

```APIDOC
## GET /v2/catalog/list

### Description
Retrieves catalog objects in batches. The endpoint does not return deleted items; use `searchObjects` with `include_deleted_objects: true` to find deleted items. Pagination limit is currently 100 items per page.

### Method
GET

### Endpoint
/v2/catalog/list

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor from previous response
- **types** (string) - Optional - Comma-separated list of object types to retrieve (ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc.)
- **catalog_version** (integer) - Optional - Retrieve historical version of catalog objects

### Response
#### Success Response (200)
- **objects** (array) - List of catalog objects
- **pagination** (object) - Pagination cursor for next page
```

--------------------------------

### Build and inspect the server

Source: https://github.com/square/square-mcp-server/blob/main/README.md

Commands to build the project and launch the MCP inspector for testing.

```bash
# Build the project
npm run build

# Start the inspector with the Square MCP Server
npx @modelcontextprotocol/inspector node dist/index.js start
```

--------------------------------

### Batch Retrieve Catalog Objects Usage

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

Example of calling batchGetobjects to retrieve multiple items and their related objects.

```typescript
const response = await make_api_request({
  service: "catalog",
  method: "batchGetobjects",
  request: {
    object_ids: ["ITEM_1", "ITEM_2", "ITEM_3"],
    include_related_objects: true
  }
});

const result = JSON.parse(response.content[0].text);
console.log(`Retrieved ${result.objects?.length || 0} objects`);
```

--------------------------------

### GET /v2/webhook-subscriptions/{subscription_id}

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/002-endpoints.md

Get subscription details.

```APIDOC
## GET /v2/webhook-subscriptions/{subscription_id}

### Description
Get subscription details.

### Method
GET

### Endpoint
/v2/webhook-subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription to retrieve.
```

--------------------------------

### Build the Project

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Command to compile the project and output to the dist directory.

```bash
npm run build
```

--------------------------------

### GET /v2/team-members/{team_member_id}

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/002-endpoints.md

Get team member details.

```APIDOC
## GET /v2/team-members/{team_member_id}

### Description
Get team member details.

### Method
GET

### Endpoint
/v2/team-members/{team_member_id}

### Parameters
#### Path Parameters
- **team_member_id** (string) - Required - The ID of the team member to retrieve.
```

--------------------------------

### List Locations TypeScript Example

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/006-locations-service.md

Retrieves all merchant locations and iterates through the results to log location details.

```typescript
const response = await make_api_request({
  service: "locations",
  method: "list",
  request: {}
});

const data = JSON.parse(response.content[0].text);
data.locations?.forEach(location => {
  console.log(`${location.id}: ${location.name} - ${location.address?.address_line_1}`);
});
```

--------------------------------

### Get order HTTP endpoint

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

The HTTP GET request path for retrieving an order by ID.

```http
GET /v2/orders/{order_id}
```

--------------------------------

### Get Catalog Object HTTP Endpoint

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

HTTP GET endpoint for retrieving a catalog object by ID.

```http
GET /v2/catalog/object/{object_id}
```

--------------------------------

### GET /v2/payments/{payment_id}

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/004-payments-service.md

Gets complete payment information including authorization, processing, and receipt details.

```APIDOC
## GET /v2/payments/{payment_id}

### Description
Gets complete payment information including authorization, processing, and receipt details.

### Method
GET

### Endpoint
/v2/payments/{payment_id}

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - ID of payment to retrieve

### Response
#### Success Response (200)
- **payment** (Object) - Payment object with all details.
```

--------------------------------

### Configure via .env File

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Uses a .env file to manage configuration variables for the server.

```text
ACCESS_TOKEN=sq_atp-...
SANDBOX=true
SQUARE_VERSION=2025-04-16
```

```bash
npx square-mcp-server start
```

--------------------------------

### Configure Environment Selection

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Toggle between sandbox and production environments using boolean flags.

```bash
SANDBOX=true npx square-mcp-server start
```

```bash
PRODUCTION=true npx square-mcp-server start
```

--------------------------------

### Discover MCP Tools

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/README.md

Use these commands to explore service information, method types, and make API requests.

```text
get_service_info({ service: "catalog" })
get_type_info({ service: "catalog", method: "list" })
make_api_request({ service: "catalog", method: "list", request: {} })
```

--------------------------------

### GET /v2/orders/{order_id}

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

Gets full order information including line items, payments, and fulfillment status.

```APIDOC
## GET /v2/orders/{order_id}

### Description
Gets full order information including line items, payments, fulfillment status.

### Method
GET

### Endpoint
/v2/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - ID of order to retrieve

### Response
#### Success Response (200)
- **order** (Object) - Order object with all details.
```

--------------------------------

### GET /v2/webhook-subscriptions

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/002-endpoints.md

List webhook subscriptions.

```APIDOC
## GET /v2/webhook-subscriptions

### Description
List webhook subscriptions.

### Method
GET

### Endpoint
/v2/webhook-subscriptions
```

--------------------------------

### Configure Square MCP Server for AI Assistants

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/README.md

Configuration snippets for integrating the server with Claude Desktop and Goose.

```json
{
  "mcpServers": {
    "square": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": { "ACCESS_TOKEN": "..." }
    }
  }
}
```

```yaml
extensions:
  square_mcp:
    cmd: "npx"
    args: ["square-mcp-server", "start"]
```

--------------------------------

### Retrieve Invoice Signature

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

TypeScript signature for the get method.

```typescript
get(request: RetrieveInvoiceRequest): Promise<RetrieveInvoiceResponse>
```

--------------------------------

### GET /v2/locations

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/006-locations-service.md

Lists all locations associated with the merchant account.

```APIDOC
## GET /v2/locations

### Description
Lists all locations for the merchant account.

### Method
GET

### Endpoint
/v2/locations

### Response
#### Success Response (200)
- **locations** (Array) - Array of Location objects.
```

--------------------------------

### create

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

Creates a new order with specified line items.

```APIDOC
## create

### Description
Creates a new order in the system.

### Method
make_api_request

### Request Body
- **order** (object) - Required - The order object containing line_items.
```

--------------------------------

### Get Catalog Object Signature

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

TypeScript signature for the getObject method.

```typescript
getObject(request: RetrieveCatalogObjectRequest): Promise<RetrieveCatalogObjectResponse>
```

--------------------------------

### GET /v2/invoices

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Lists invoices with optional time filtering and pagination.

```APIDOC
## GET /v2/invoices

### Description
Lists invoices with optional time filtering.

### Method
GET

### Endpoint
/v2/invoices

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor
- **limit** (integer) - Optional - Max results (1-100)
- **begin_time** (string) - Optional - Start time (RFC 3339)
- **end_time** (string) - Optional - End time (RFC 3339)
- **sort_field** (string) - Optional - Field to sort by
- **sort_order** (string) - Optional - ASC or DESC

### Response
#### Success Response (200)
- **invoices** (Array) - Array of Invoice objects.
```

--------------------------------

### Configure Claude Desktop for Local MCP

Source: https://github.com/square/square-mcp-server/blob/main/README.md

Add this configuration to claude_desktop_config.json to run the server locally with a Square access token.

```json
{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN",
        "SANDBOX": "true"
      }
    }
  }
}
```

--------------------------------

### Configure Claude Desktop with Remote OAuth

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Recommended configuration for production use to leverage OAuth authentication.

```json
{
  "mcpServers": {
    "mcp_square_api_remote": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.squareup.com/sse"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "square_remote": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.squareup.com/sse"]
    }
  }
}
```

--------------------------------

### Tax JSON Representation

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/004-types-reference.md

Example of an additive sales tax configuration.

```json
{
  "name": "Sales Tax",
  "percentage": "8.5",
  "type": "ADDITIVE"
}
```

--------------------------------

### Create and Pay Order Workflow

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

Sequential process to create an order, process a payment, link the payment to the order, and close the order.

```typescript
// 1. Create order
const orderResp = await make_api_request({
  service: "orders",
  method: "create",
  request: {
    order: {
      line_items: [{
        name: "Pizza",
        quantity: "1",
        gross_sales_money: { amount: 1500, currency: "USD" }
      }]
    }
  }
});

const order = JSON.parse(orderResp.content[0].text).order;

// 2. Process payment
const paymentResp = await make_api_request({
  service: "payments",
  method: "create",
  request: {
    source_id: "ccof:...",
    amount_money: { amount: 1500, currency: "USD" },
    idempotency_key: "payment-123"
  }
});

const payment = JSON.parse(paymentResp.content[0].text).payment;

// 3. Link payment to order
await make_api_request({
  service: "orders",
  method: "payOrder",
  request: {
    order_id: order.id,
    payment_ids: [payment.id],
    idempotency_key: "pay-order-123"
  }
});

// 4. Close order
await make_api_request({
  service: "orders",
  method: "closeOrder",
  request: { order_id: order.id }
});
```

--------------------------------

### Get Payment HTTP Request

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/004-payments-service.md

The HTTP endpoint for retrieving a payment by ID.

```http
GET /v2/payments/{payment_id}
```

--------------------------------

### Get order method signature

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

TypeScript signature for retrieving a specific order.

```typescript
get(request: RetrieveOrderRequest): Promise<RetrieveOrderResponse>
```

--------------------------------

### Create and Publish Invoice

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/007-invoices-service.md

Demonstrates the two-step process of creating a draft invoice and subsequently publishing it to the customer.

```typescript
// Quick send: create, publish in one flow
const response = await make_api_request({
  service: "invoices",
  method: "create",
  request: {
    invoice: {
      invoice_number: "INV-2024-001",
      customer_id: "CUST_456",
      primary_recipient: { customer_id: "CUST_456" },
      payment_requests: [
        {
          request_type: "BALANCE",
          due_date: "2024-02-20"
        }
      ]
    }
  }
});

const draft = JSON.parse(response.content[0].text).invoice;
const pubResp = await make_api_request({
  service: "invoices",
  method: "publish",
  request: {
    invoice_id: draft.id,
    version: 0
  }
});

const published = JSON.parse(pubResp.content[0].text).invoice;
console.log(`Sent to customer: ${published.invoice_url}`);
```

--------------------------------

### Project Directory Structure

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/README.md

Overview of the documentation file organization.

```text
output/
├── README.md                          (this file)
├── 000-index.md                       (navigation guide)
├── 001-overview.md                    (architecture)
├── 002-endpoints.md                   (service listing)
├── 003-configuration.md               (setup & config)
├── 004-types-reference.md             (data types)
└── api-reference/
    ├── 001-mcp-tools.md               (main tools)
    ├── 002-catalog-service.md         (catalog API)
    ├── 003-customers-service.md       (customers API)
    ├── 004-payments-service.md        (payments API)
    ├── 005-orders-service.md          (orders API)
    ├── 006-locations-service.md       (locations API)
    └── 007-invoices-service.md        (invoices API)
```

--------------------------------

### Define environment variables in .env

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Create a .env file in the working directory to set configuration variables.

```bash
# .env
ACCESS_TOKEN=sq_atp-...
SANDBOX=true
SQUARE_VERSION=2024-08-01
```

--------------------------------

### Get Payment TypeScript Signature

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/004-payments-service.md

The TypeScript method signature for retrieving a specific payment.

```typescript
get(request: RetrievePaymentRequest): Promise<RetrievePaymentResponse>
```

--------------------------------

### List orders HTTP endpoint

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/005-orders-service.md

The HTTP GET request path for listing orders.

```http
GET /v2/orders
```

--------------------------------

### Validate Server Configuration

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/003-configuration.md

Checks environment variables at startup to prevent conflicting settings and determines the appropriate base URL.

```typescript
// Validates
if (process.env.SANDBOX == "true" && process.env.PRODUCTION == "true") {
  throw new Error("Both SANDBOX and PRODUCTION env vars are true");
}

// Sets base URL based on config
const baseUrl = process.env.SANDBOX === "true" 
  ? "https://connect.squareupsandbox.com"
  : "https://connect.squareup.com"
```

--------------------------------

### Tool usage phases

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/001-overview.md

Standard workflow for interacting with Square API tools, involving discovery, schema preparation, and final execution.

```text
Tool: get_service_info
Input: { service: "catalog" }
Output: List of available methods with descriptions
```

```text
Tool: get_type_info
Input: { service: "catalog", method: "list" }
Output: Complete schema for ListCatalogRequest
```

```text
Tool: make_api_request
Input: { service: "catalog", method: "list", request: { types: "ITEM" } }
Output: API response or error
```

--------------------------------

### List Customers HTTP Endpoint

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/003-customers-service.md

The HTTP GET endpoint for retrieving customer profiles.

```http
GET /v2/customers
```

--------------------------------

### List Catalog Objects HTTP Endpoint

Source: https://github.com/square/square-mcp-server/blob/main/_autodocs/api-reference/002-catalog-service.md

The HTTP GET endpoint for listing catalog objects.

```http
GET /v2/catalog/list
```

--------------------------------

### Understand parameter requirements

Source: https://github.com/square/square-mcp-server/blob/main/README.md

Use get_type_info to retrieve parameter requirements for a specific service method.

```text
get_type_info(service: "catalog", method: "list")
```
Tokens:
Raw