Respond.io MCP Server

A Model Context Protocol (MCP) server implementation for the Respond.io API, enabling seamless integration with AI assistants, automation tools, and Claude Desktop.

Features

Contact Management

✅ Get, create, update, and delete contacts
✅ List contacts with filters and search
✅ Add and remove contact tags
✅ Update contact lifecycle stages
✅ List contact channels

Messaging

✅ Send messages (text, attachments, WhatsApp templates, emails)
✅ Retrieve message details and status
✅ Support for multiple channel types

Conversations

✅ Assign/unassign conversations to users
✅ Open and close conversations
✅ Add closing notes and summaries

Workspace Management

✅ List users and get user details
✅ Manage custom fields
✅ List channels and closing notes
✅ Create and manage workspace tags

Comments

✅ Add internal comments to contacts
✅ Mention users in comments

HTTP/STDIO Dual Mode

✅ Can run as a local subprocess via stdio or as an HTTP server (/mcp endpoint)
✅ Health endpoint (/health) for monitoring and uptime checks
✅ CORS enabled for HTTP mode

Prerequisites

Node.js 18+
npm / yarn / bun
Git

Installation

# Clone the repository
git clone https://github.com/respond-io/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

The server is configured using environment variables. Set them in your shell or deployment environment.

RESPONDIO_API_KEY: (Required) Your Respond.io API key.
RESPONDIO_BASE_URL: The base URL for the Respond.io API (defaults to https://api.respond.io/v2).
MCP_SERVER_MODE: The server mode, either stdio or http (defaults to stdio).
PORT: The port for HTTP mode (defaults to 3000).

Usage with Claude Desktop

You can use this server with Claude Desktop in either STDIO (local subprocess) or HTTP (hosted or local HTTP server) mode.

1️⃣ STDIO Mode (Recommended for local Claude Desktop)

Configure Claude Desktop (For Development Purpose):

{
      "command": "node",
      "args": [
        "/<Your Local Folder Path>/dist/index.js"
      ],
      "env": {
        "RESPONDIO_API_KEY": "your_api_key",
        "MCP_SERVER_MODE": "stdio"
      }
    }

Configure Claude Desktop (For Production Usage):

{
      "command": "npx",
      "args": [
        "@respond-io/mcp-server"
      ],
      "env": {
        "RESPONDIO_API_KEY": "your_api_key",
        "MCP_SERVER_MODE": "stdio"
      }
    }

Launch Claude Desktop and add this MCP server.
The server will start as a subprocess and communicate over stdio.

Test:
Try any MCP tool from Claude Desktop, e.g., get a contact or send a message.

2️⃣ HTTP Mode (For remote/hosted or local HTTP integration)

Start the server in HTTP mode:

npm run start:http

or (if built):

export MCP_SERVER_MODE=http
node dist/index.js

Configure Claude Desktop:

{
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-token-here"
      }
    }

Test HTTP health:

curl http://localhost:3000/health
# {"status":"ok"}

Test HTTP MCP endpoint:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"list_tools","params":{}}'

You should get a JSON list of available tools.

Usage Examples

Contact Management

Get a Contact

get_contact({ identifier: "id:12345" })
get_contact({ identifier: "email:user@example.com" })
get_contact({ identifier: "phone:+60123456789" })

Create a Contact

create_contact({
  identifier: "phone:+60123456789",
  firstName: "John",
  lastName: "Doe",
  email: "john.doe@example.com",
  language: "en",
  custom_fields: [
    { name: "Company", value: "Acme Corp" },
    { name: "Order Number", value: 12345 }
  ]
})

List Contacts with Filters

list_contacts({
  limit: 50,
  search: "john@example.com",
  timezone: "Asia/Kuala_Lumpur"
})

Add Tags

add_contact_tags({
  identifier: "id:12345",
  tags: ["vip", "premium", "sales"]
})

Messaging

Send Text Message

send_message({
  identifier: "id:12345",
  channelId: null, // Use last interacted channel
  messageType: "text",
  text: "Hello! Thank you for contacting us."
})

Send WhatsApp Template

send_message({
  identifier: "phone:+60123456789",
  channelId: 5678,
  messageType: "whatsapp_template",
  templateName: "order_confirmation",
  templateLanguage: "en"
})

Send Email

send_message({
  identifier: "email:user@example.com",
  channelId: 1234,
  messageType: "email",
  text: "Your order has been shipped!",
  subject: "Order Shipment Notification"
})

Send Attachment

send_message({
  identifier: "id:12345",
  channelId: 5678,
  messageType: "attachment",
  attachmentUrl: "https://example.com/invoice.pdf",
  attachmentType: "file"
})

Conversations

Assign Conversation

assign_conversation({
  identifier: "id:12345",
  assignee: "123"
})
assign_conversation({
  identifier: "id:12345",
  assignee: "agent@example.com"
})
assign_conversation({
  identifier: "id:12345",
  assignee: "null"
})

Close Conversation

update_conversation_status({
  identifier: "id:12345",
  status: "close",
  category: "Resolved",
  summary: "Customer issue resolved successfully"
})

Comments

Add Comment

create_comment({
  identifier: "id:12345",
  text: "Customer requested a callback tomorrow at 2 PM"
})
// Mention a user
create_comment({
  identifier: "id:12345",
  text: "{{@user.456}} please follow up with this customer"
})

Workspace Management

List Users

list_users({
  limit: 20
})

Create Custom Field

create_custom_field({
  name: "Customer Tier",
  slug: "customer_tier",
  description: "Customer membership tier",
  dataType: "list",
  allowedValues: ["Bronze", "Silver", "Gold", "Platinum"]
})

List Channels

list_channels({
  limit: 10
})

Available Tools

Contact Tools

get_contact - Retrieve contact information
create_contact - Create a new contact
update_contact - Update contact information
delete_contact - Delete a contact
list_contacts - List all contacts with filters
add_contact_tags - Add tags to a contact
remove_contact_tags - Remove tags from a contact

Messaging Tools

send_message - Send messages (text, attachment, template, email)
get_message - Retrieve message details

Conversation Tools

assign_conversation - Assign/unassign conversations
update_conversation_status - Open/close conversations

Comment Tools

create_comment - Add internal comments

Workspace Tools

list_users - List workspace users
get_user - Get user details
list_custom_fields - List custom fields
create_custom_field - Create custom fields
list_channels - List messaging channels
list_closing_notes - List closing note categories

Development

Project Structure

mcp-server/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── middlewares/      # Express middlewares
│   ├── utils/            # Utility functions
│   └── tools/            # Tool definitions
├── dist/                 # Compiled JavaScript output
├── .env.example          # Environment variable template
├── .eslintrc.json        # ESLint configuration
├── .prettierrc.json      # Prettier configuration
├── tsconfig.json         # TypeScript configuration
├── package.json          # Project dependencies
└── README.md             # Documentation

Development Commands

# Run in development mode with auto-reload
npm run dev

# Build the project
npm run build

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type check
npm run type-check

Code Quality

✅ TypeScript - Full type safety
✅ ESLint - Code quality and consistency
✅ Prettier - Code formatting
✅ Strict Mode - TypeScript strict mode enabled
✅ Error Handling - Comprehensive error handling
✅ Modular Design - Clean separation of concerns

API Rate Limits

The Respond.io API has rate limits. The server handles rate limit errors and includes rate limit information in error responses:

Retry-After - Seconds until retry is allowed
X-RateLimit-Limit - Request limit for the endpoint
X-RateLimit-Remaining - Remaining requests

Error Handling

The server provides detailed error messages:

// API errors include status codes and messages
{
  "error": "API Error 404: Contact not found"
}

// Network errors
{
  "error": "Network Error: timeout of 30000ms exceeded"
}

// Validation errors
{
  "error": "API Error 400: Validation error."
}

Security Best Practices

Never commit API keys - Use environment variables
Use HTTPS - All API calls use secure connections
Validate input - All inputs are validated before API calls
Error sanitization - Sensitive information is not exposed in errors

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Follow TypeScript best practices
Use meaningful variable and function names
Add comments for complex logic
Ensure all tests pass
Run linter before committing

Troubleshooting

"UN_AUTHORIZED" Error

Check that your API key is correct in .env
Ensure the API key has the necessary permissions

"Contact not found" Error

Verify the contact identifier format (id:123, email:user@example.com, phone:+60123456789)
Check that the contact exists in your workspace

Rate Limit Errors

Wait for the time specified in the Retry-After header
Consider implementing exponential backoff for retries

Build Errors

Run npm install to ensure all dependencies are installed
Delete node_modules and dist folders, then reinstall

TypeScript/ESLint Warnings

Ensure you are using a supported TypeScript version (recommended: 5.3.x)
If you see warnings about any, use Record<string, unknown> or define explicit interfaces

Health Check Fails

Ensure the MCP server is running in HTTP mode (MCP_SERVER_MODE=http)
Check the correct port (PORT) is open and matches your configuration
Use curl http://localhost:3000/health to test

License

MIT License - see LICENSE file for details

Support

For issues and questions:

GitHub Issues: [Create an issue]
Respond.io API Documentation: https://docs.respond.io
Respond.io Support: https://support.respond.io

Changelog

Version 1.0.0

Initial release
Full support for Contact, Messaging, Conversation, Comment, and Space APIs
Comprehensive error handling
TypeScript with strict mode
MCP SDK integration
HTTP and STDIO dual-mode support
Health endpoint for monitoring

Acknowledgments

Built with Model Context Protocol SDK
Powered by Respond.io API

Made with ❤️ for seamless customer engagement automation

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
public		public
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
API_REFERENCE.md		API_REFERENCE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

respond-io/mcp-server

Folders and files

Latest commit

History

Repository files navigation

Respond.io MCP Server

Features

Contact Management

Messaging

Conversations

Workspace Management

Comments

HTTP/STDIO Dual Mode

Prerequisites

Installation

Configuration

Environment Variables

Usage with Claude Desktop

1️⃣ STDIO Mode (Recommended for local Claude Desktop)

2️⃣ HTTP Mode (For remote/hosted or local HTTP integration)

Usage Examples

Contact Management

Get a Contact

Create a Contact

List Contacts with Filters

Add Tags

Messaging

Send Text Message

Send WhatsApp Template

Send Email

Send Attachment

Conversations

Assign Conversation

Close Conversation

Comments

Add Comment

Workspace Management

List Users

Create Custom Field

List Channels

Available Tools

Contact Tools

Messaging Tools

Conversation Tools

Comment Tools

Workspace Tools

Development

Project Structure

Development Commands

Code Quality

API Rate Limits

Error Handling

Security Best Practices

Contributing

Code Style

Troubleshooting

"UN_AUTHORIZED" Error

"Contact not found" Error

Rate Limit Errors

Build Errors

TypeScript/ESLint Warnings

Health Check Fails

License

Support

Changelog

Version 1.0.0

Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Packages