SparrowDesk MCP Server

A Model Context Protocol (MCP) server for SparrowDesk. Connect AI assistants like Claude to your SparrowDesk account to read and manage tickets, contacts, Knowledge Base content, tags, companies, and team data.

Authentication is handled via OAuth — no API keys to manage. Your MCP client will open a browser window to log in with your SparrowDesk account the first time you connect.

Available Tools

Tools mirror the SparrowDesk Developer API. Knowledge Base collections and related endpoints require VIEW_COLLECTIONS and MANAGE_COLLECTIONS (included in the MCP default OAuth scope list). Other KB behavior may still depend on additional scopes or account features.

Installing in Claude

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "sparrowdesk": {
      "type": "http",
      "url": "https://mcp.sparrowdesk.com/mcp"
    }
  }
}

Or with Claude Code:

claude mcp add --transport http sparrowdesk https://mcp.sparrowdesk.com/mcp

Installing in Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sparrowdesk": {
      "type": "http",
      "url": "https://mcp.sparrowdesk.com/mcp"
    }
  }
}

Restart Cursor after saving. The SparrowDesk tools will appear in the Agent tool list. Cursor will open a browser window to complete the OAuth login with your SparrowDesk account.

Tool Reference

get_conversation

Fetch a single conversation by its numeric ID.

Parameters:

• id (integer, required) — The conversation ID

list_conversations

List conversations with optional filters, sorting, and pagination.

Parameters:

• starting_after (string, optional) — Pagination cursor
• per_page (integer, optional) — Items per page, 1–100 (default: 25)
• status (array, optional) — Filter by status: Open, Pending, Resolved, Closed
• priority (array, optional) — Filter by priority: Low, Medium, High, Urgent
• assigned_to_member_id (array of integers, optional) — Filter by assigned agent IDs
• assigned_to_team_id (array of integers, optional) — Filter by assigned team IDs
• brand_id (array of integers, optional) — Filter by brand IDs
• requested_by_id (integer, optional) — Filter by requestor contact ID
• requested_by_company (integer, optional) — Filter by requester contact company ID (intersects with requested_by_id when both are set)
• sort_by (string, optional) — created_at or updated_at (default: created_at)
• sort_order (string, optional) — asc or desc (default: desc)

list_conversations_with_replies

List conversations with their replies inlined in a single call — the same filters as list_conversations, plus reply controls. Root pages / total_count apply to conversations only; each row carries a replies object shaped like list_conversation_replies.

Parameters:

• starting_after (string, optional) — Cursor for conversation list pagination
• per_page (integer, optional) — Conversations per page, 1–20 (default: 20)
• replies_per_page (integer, optional) — Replies per conversation, 1–50 (default: 50)
• replies_sort_order (string, optional) — Reply sort by sent_at: asc or desc (default: desc)
• type (string, optional) — Filter replies by INTERNAL_NOTE or REPLY
• status, priority, assigned_to_member_id, assigned_to_team_id, brand_id, requested_by_id — Same conversation filters as list_conversations
• handled_by_ai_agent (boolean, optional) — Filter by whether the conversation was handled by the AI agent
• sort_by (string, optional) — created_at or updated_at (default: created_at)
• sort_order (string, optional) — asc or desc (default: desc)

update_conversation

Patch an existing conversation.

Parameters:

• id (integer, required) — Conversation ID
• subject, priority, status, assignee (email), team (string) — Optional updates
• custom_fields (array, optional) — { internal_name, value } (values as strings)

delete_conversation

Delete a conversation by ID.

Parameters:

• id (integer, required)

list_conversation_replies

List replies for a conversation, with optional filtering and pagination.

Parameters:

• id (integer, required) — The conversation ID
• starting_after (string, optional) — Pagination cursor
• per_page (integer, optional) — Items per page, 1–100 (default: 25)
• type (string, optional) — Filter by INTERNAL_NOTE or REPLY
• sort_order (string, optional) — asc or desc (default: desc)

add_conversation_reply

Add a reply or internal note to a conversation.

Parameters:

• id (integer, required) — The conversation ID
• reply_text (string, required) — The content of the reply message
• type (string, required) — REPLY (visible to customer) or INTERNAL_NOTE (agents only)

create_conversation

Create a new conversation/ticket in SparrowDesk.

Parameters:

• subject (string, required) — Conversation subject
• description (string, required) — Conversation description
• requested_by (string, required) — Email or phone number of the requester
• priority (string, optional) — Low, Medium, High, or Urgent (default: Medium)
• source (string, optional) — Mail or Call (default: Call)
• status (string, optional) — Open, Pending, Resolved, or Closed (default: Open)
• brand_id (integer, optional) — Brand ID (uses account default if omitted)
• assignee (string, optional) — Agent email address to assign the conversation to
• team_id (integer, optional) — Team ID to assign the conversation to
• custom_fields (array, optional) — Array of { internal_name, value } objects

Conversation field tools

• list_conversation_fields — starting_after, per_page, is_active, is_default
• get_conversation_field — id
• create_conversation_field — name, type (single_line_text | multi_line_text | dropdown | number | date | email), optional internal_name, description, is_mandatory_on_close, field_options (required for dropdowns)
• update_conversation_field — id plus any of name, description, is_active, is_mandatory_on_close, field_options

list_contacts

List contacts with filters (requires view contacts scope where enforced).

Parameters: search, requested_by_email, requested_by_phone, starting_after, per_page

delete_contact

Parameters: id (integer, required)

bulk_create_contacts / get_bulk_job_status

Bulk create accepts contacts: array of objects with optional first_name, last_name, email, phone, company_id, custom_fields. Response includes job_id. Poll get_bulk_job_status with job_id until completed or failed.

list_companies

Parameters: starting_after, per_page, domain (exact), name (exact)

get_company

Parameters: id (integer, required)

create_company

Create a new company.

Parameters:

• name (string, required) — Company name
• domain (string, optional) — Lowercase domain like example.com
• address (string, optional) — Company address
• notes (string, optional) — Free-form notes

update_company

Update an existing company. At least one field must be provided.

Parameters:

• id (integer, required) — The company ID to update
• name, domain, phone, address, notes — Optional updates

create_contact

Create a new contact. Either email or phone must be provided.

Parameters:

• first_name (string, required) — Contact's first name
• last_name (string, optional) — Contact's last name
• email (string, optional) — Contact's email address (required if phone not provided)
• phone (string, optional) — Contact's phone number (required if email not provided)
• company_id (integer, optional) — ID of the company to associate with
• custom_fields (object, optional) — Custom field key-value pairs

update_contact

Update an existing contact.

Parameters:

• id (integer, required) — The contact ID to update
• first_name (string, optional) — Contact's first name
• last_name (string, optional) — Contact's last name
• email (string, optional) — Contact's email address
• phone (string, optional) — Contact's phone number
• company_id (integer, optional) — ID of the company to associate with
• blocked (boolean, optional) — Whether the contact is blocked
• custom_fields (object, optional) — Custom field key-value pairs

get_contact

Fetch a single contact by its numeric ID.

Parameters:

• id (integer, required) — The contact ID

list_contact_fields

Retrieve all contact fields defined in the account.

Parameters:

• search (string, optional) — Search contact fields by name
• page (integer, optional) — Page number for pagination
• limit (integer, optional) — Results per page

list_members

Retrieve a paginated list of all team members in the account.

Parameters:

• starting_after (string, optional) — Pagination cursor
• per_page (integer, optional) — Items per page, 1–100 (default: 25)

get_me

Retrieve current SparrowDesk account information (not a user profile).

Parameters: None

list_tags

Parameters: starting_after, per_page, search

Knowledge Base tools

Use list_helpcenters first to obtain helpCenterId. Collections and articles are scoped per help center and brand.

• list_collections — helpCenterId (required); optional page, limit, collectionId, isRoot
• get_collection — id; optional page, limit for articles
• create_collection — name, helpCenterId, brandId; optional description, parentCollectionId
• list_articles — helpCenterId (required); optional published, draft, archived, page, limit, search, collectionId
• get_article — id
• create_article — helpCenterId, brandId; optional title, content (HTML), publish, collectionId, isPublic (publish flow per API docs)
• update_article — id; optional title, content, collectionId (null to remove from collection), brandId, publish, isPublic, aiAgentEnabled, aiCopilotEnabled
• archive_article — id

Local Development

See SETUP.md for local development instructions, environment variables, and Docker setup.