Groove MCP Server

A Model Context Protocol (MCP) server for Groove HQ, providing access to customer support ticketing, CRM, and knowledge base functionality through the Groove GraphQL API v2.

Installation

npm install
npm run build

Configuration

Create a .env file with your Groove API credentials:

GROOVE_API_TOKEN=your_groove_api_token_here
GROOVE_API_URL=https://api.groovehq.com/v2/graphql  # Optional, this is the default

Usage

Run the server:

npm start

Or use it with an MCP client by pointing to the executable:

node dist/index.js

Available Tools

Conversation Management

• listConversations - List conversations with optional filters

  • status: Filter by status (unread, opened, closed, snoozed)
  • assigneeId: Filter by assigned agent ID
  • contactId: Filter by contact ID
  • tagIds: Filter by tag IDs
  • limit: Maximum number of conversations to return (default: 20)

• getConversation - Get detailed information about a specific conversation

  • id: The conversation ID (required)

• createConversation - Create a new conversation

  • contactId: ID of the contact (required)
  • subject: Subject of the conversation (required)
  • body: Initial message body (required)
  • assigneeId: ID of agent to assign to
  • tagIds: Tag IDs to apply

• updateConversation - Update a conversation

  • id: The conversation ID (required)
  • status: New status (opened, closed, snoozed)
  • assigneeId: ID of agent to assign to
  • tagIds: Tag IDs to apply
  • snoozedUntil: ISO 8601 datetime to snooze until

• closeConversation - Close a conversation

  • id: The conversation ID to close (required)

Message Operations

• listMessages - List messages in a conversation

  • conversationId: The conversation ID to list messages for (required)
  • limit: Maximum number of messages to return (default: 50)
  • after: Cursor for pagination

• sendMessage - Send a message in a conversation

  • conversationId: The conversation ID to send message to (required)
  • body: The message body content (required)
  • attachmentIds: IDs of attachments to include

• createNote - Create an internal note in a conversation

  • conversationId: The conversation ID to add note to (required)
  • body: The note content (required)

Contact Management

• listContacts - List contacts with optional search

  • search: Search string to filter contacts
  • limit: Maximum number of contacts to return (default: 20)
  • after: Cursor for pagination

• getContact - Get detailed information about a specific contact

  • id: The contact ID (required)

• createContact - Create a new contact

  • email: Contact email address (required)
  • firstName: Contact first name
  • lastName: Contact last name
  • company: Contact company
  • title: Contact job title
  • phone: Contact phone number

• updateContact - Update contact information

  • id: The contact ID (required)
  • email: Contact email address
  • firstName: Contact first name
  • lastName: Contact last name
  • company: Contact company
  • title: Contact job title
  • phone: Contact phone number

Agent Operations

• listAgents - List all agents in the organization

• getAgent - Get detailed information about a specific agent

  • id: The agent ID (required)

• getAvailableAgents - List all available agents

Knowledge Base

• searchKbArticles - Search knowledge base articles
  • query: Search query (required)
  • limit: Maximum number of articles to return (default: 20)

Resources

The server exposes Knowledge Base articles as MCP resources. These can be browsed and read by MCP clients.

• Knowledge Base Articles - Published KB articles are available as resources
  • Each article includes metadata like category, views, and helpful votes
  • Articles are returned in Markdown format when read

Development

# Watch mode for development
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run typecheck

Project Structure

├── src/
│   ├── index.ts           # Main server entry point
│   ├── groove-client.ts   # GraphQL client wrapper
│   ├── tools/             # MCP tool implementations
│   │   ├── conversations.ts
│   │   ├── messages.ts
│   │   ├── contacts.ts
│   │   └── agents.ts
│   ├── resources/         # MCP resource implementations
│   │   └── kb-articles.ts
│   ├── types/             # TypeScript type definitions
│   │   └── groove.ts
│   └── utils/             # Utility functions
│       └── graphql-queries.ts
├── tests/                 # Test files
├── docs/                  # Documentation
└── dist/                  # Compiled JavaScript files

License

MIT