Frontapp MCP server

The Frontapp Model Context Protocol (MCP) server acts as a bridge between Large Language Models (LLMs) and Frontapp's customer communication platform. It enables LLMs to access and manipulate Frontapp data and automate workflows using natural language commands, with support for real-time updates through webhooks.

Prerequisites

Before installing the Frontapp MCP server, ensure you have:

• Node.js (v16 or higher)
• npm or yarn
• Frontapp API credentials
• A publicly accessible URL for webhooks (for production use)

Installation Options

Option 1: Install via Smithery

For automatic installation with Claude Desktop:

npx -y @smithery/cli install @zqushair/frontapp-mcp --client claude

Option 2: Manual Installation

1. Clone the repository:

   git clone https://github.com/zqushair/Frontapp-MCP.git
   cd Frontapp-MCP
   

2. Install dependencies:

   npm install
   

3. Create and configure the .env file:

   cp .env.example .env
   # Edit the .env file with your Frontapp API credentials
   

4. Build and start the project:

   npm run build
   npm start
   

Docker Deployment

The project includes a Dockerfile for containerized deployment.

Building and Running with Docker

# Build the Docker image
docker build -t frontapp-mcp .

# Run the Docker container
docker run -p 3000:3000 --env-file .env frontapp-mcp

Using the MCP Server

API Usage

The server exposes tools that can be called by LLMs through the MCP protocol for interacting with Frontapp data including:

• Conversation management
• Contact management
• Tag management
• Inbox and user management
• Webhook handling

Client Library

Use the included TypeScript client library to interact with the MCP server:

import { FrontappMcpClient } from './frontapp-mcp-client.js';

// Create a client instance
const client = new FrontappMcpClient('http://localhost:3000');

// Get a list of conversations
const conversations = await client.getConversations({ status: 'open' });

// Send a message to a conversation
await client.sendMessage('cnv_123', 'Hello, how can I help you today?');

The client library provides:

• Type-safe methods for all available tools
• Error handling with custom error handlers
• Retry logic with exponential backoff
• Comprehensive TypeScript interfaces

Webhook Integration

For real-time updates from Frontapp, the server supports webhook integration. This allows the system to respond automatically to events such as:

• New messages
• Status changes
• Tag modifications
• Contact updates

Security Best Practices

• Store API credentials securely using the credential manager with AES-256 encryption
• Generate strong encryption keys: npm run generate-key
• Enable HTTPS for all communications: npm run generate-cert (for development)
• Use certificates from trusted certificate authorities for production
• Verify webhook signatures to ensure they come from Frontapp
• Implement rate limiting to prevent abuse
• Validate all incoming data to prevent injection attacks

Running in Development Mode

For development with hot reloading:

npm run dev

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "frontapp-mcp" '{"command":"npx","args":["-y","@zqushair/frontapp-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "frontapp-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@zqushair/frontapp-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "frontapp-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@zqushair/frontapp-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect