Skip to main content
Glama
Sign In
SeaTalk MCP Server

SeaTalk MCP Server

by mukung26
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

SeaTalk MCP Server

This server provides Model Context Protocol (MCP) tools to interact with the SeaTalk API. It enables AI assistants to send and retrieve messages, access employee information, and interact with group chats via SeaTalk.

Setup

  1. Install dependencies:

    npm install

  2. Create a .env file with your SeaTalk credentials:

    SEATALK_APP_ID=your_app_id
SEATALK_APP_SECRET=your_app_secret

  3. Build the server:

    npm run build

  4. Start the server:

    npm start

Related MCP server: lark-mcp

Installation

You can install this package via npm:

# Install globally
npm install -g seatalk-mcp-server

# Or use directly with npx (auto-install without prompts)
npx -y seatalk-mcp-server

NPX Usage

This package can be used directly via npx without installing it globally. The -y flag automatically accepts installation prompts for seamless automation.

Configuration in MCP Settings

Configure the SeaTalk server in your MCP settings by providing the required environment variables:

{
  "mcpServers": {
    "seatalk-mcp-server": {
      "command": "npx",
      "args": ["-y", "seatalk-mcp-server"],
      "env": {
        "SEATALK_APP_ID": "your_app_id_here",
        "SEATALK_APP_SECRET": "your_app_secret_here"
      },
      "disabled": false
    }
  }
}

Required environment variables:

  • SEATALK_APP_ID: Your SeaTalk application ID

  • SEATALK_APP_SECRET: Your SeaTalk application secret

Using with Cursor or other MCP-compatible tools

After configuring the server in your MCP settings, SeaTalk tools will be available for use in Cursor or other MCP-compatible environments.

Local Development & Manual Build

If you prefer to clone the repository and build the server yourself, follow these steps:

Prerequisites

  • Node.js 16.0.0 or higher

  • npm or yarn package manager

Clone and Build

  1. Clone the repository:

    git clone https://github.com/muhammad-iqbal/seatalk-mcp-server.git
cd seatalk-mcp-server/seatalk-server

  2. Install dependencies:

    npm install

  3. Create environment configuration:

    # Create .env file with your credentials
echo "SEATALK_APP_ID=your_app_id_here" > .env
echo "SEATALK_APP_SECRET=your_app_secret_here" >> .env

  4. Build the project:

    npm run build

  5. Run the server directly:

    node build/index.js

Configuration in MCP Settings (Local Build)

When using the locally built version, configure your MCP settings to point to the built file:

{
  "mcpServers": {
    "seatalk-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/seatalk-mcp-server/seatalk-server/build/index.js"],
      "env": {
        "SEATALK_APP_ID": "your_app_id_here",
        "SEATALK_APP_SECRET": "your_app_secret_here"
      },
      "disabled": false
    }
  }
}

Note: Replace /path/to/your/seatalk-mcp-server/seatalk-server/build/index.js with the actual absolute path to your built index.js file.

Development Workflow

For active development, you can use the watch mode:

# Build and watch for changes
npm run watch

# In another terminal, run the server
node build/index.js

This approach is useful for:

  • Contributing to the project

  • Customizing the server for specific needs

  • Testing unreleased features

  • Running in environments where npx is not available

Available Tools

Employee Information

get_employee_profile

Get an employee's profile by employee code.

Example:

{
  "employee_code": "EMP123"
}

Response:

{
  "code": 0,
  "employee": {
    "employee_code": "EMP123",
    "name": "John Doe",
    "company_email": "john.doe@company.com",
    "department": {
      "department_code": "DEP001",
      "department_name": "Engineering"
    }
  }
}

get_employee_code_with_email

Get employee codes by email addresses.

Example:

{
  "emails": ["john.doe@company.com", "jane.smith@company.com"]
}

Response:

{
  "code": 0,
  "results": [
    {
      "email": "john.doe@company.com",
      "employee_code": "EMP123",
      "exists": true
    },
    {
      "email": "jane.smith@company.com",
      "employee_code": "EMP456",
      "exists": true
    }
  ]
}

check_employee_existence

Verify whether employees exist in the organization via SeaTalk ID.

Example:

{
  "id": "ST12345"
}

Response:

{
  "code": 0,
  "exists": true
}

get_user_language_preference

Get a user's language preference.

Example:

{
  "employee_code": "EMP123"
}

Response:

{
  "code": 0,
  "language": "en"
}

Group Chat Management

get_joined_group_chat_list

Obtain group chats the bot joined.

Example:

{
  "page_size": 10
}

Response:

{
  "code": 0,
  "groups": [
    {
      "group_id": "group123",
      "group_name": "Engineering Team",
      "member_count": 15
    },
    {
      "group_id": "group456",
      "group_name": "Project Alpha",
      "member_count": 8
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_token_for_next_page"
}

get_group_info

Get information about a group chat, including member list.

Example:

{
  "group_id": "group456"
}

Response:

{
  "code": 0,
  "group_info": {
    "group_id": "group456",
    "group_name": "Project Alpha",
    "description": "Group for Project Alpha discussion",
    "created_at": 1615000000,
    "owner": {
      "employee_code": "EMP123",
      "name": "John Doe"
    }
  },
  "members": [
    {
      "employee_code": "EMP123",
      "name": "John Doe",
      "is_admin": true
    },
    {
      "employee_code": "EMP456",
      "name": "Jane Smith",
      "is_admin": false
    }
  ],
  "has_more": false
}

Messaging

get_thread_by_thread_id

Retrieve all messages within a thread of a group chat.

Example:

{
  "group_id": "group456",
  "thread_id": "thread123",
  "page_size": 20
}

Response:

{
  "code": 0,
  "messages": [
    {
      "message_id": "msg001",
      "sender": {
        "employee_code": "EMP123",
        "name": "John Doe"
      },
      "tag": "text",
      "text": {
        "plain_text": "Hello team!"
      },
      "created_at": 1615456789
    }
  ],
  "has_more": false
}

get_message_by_message_id

Retrieve a message by its message ID.

Example:

{
  "message_id": "msg001"
}

Response:

{
  "code": 0,
  "message_id": "msg001",
  "sender": {
    "employee_code": "EMP123",
    "name": "John Doe"
  },
  "tag": "text",
  "text": {
    "plain_text": "Hello team!"
  },
  "created_at": 1615456789
}

get_chat_history

Obtain the group chat history (messages sent within 7 days).

Example:

{
  "group_id": "group456",
  "page_size": 50
}

Response:

{
  "code": 0,
  "messages": [
    {
      "message_id": "msg001",
      "sender": {
        "employee_code": "EMP123",
        "name": "John Doe"
      },
      "tag": "text",
      "text": {
        "plain_text": "Hello team!"
      },
      "created_at": 1615456789
    },
    {
      "message_id": "msg002",
      "sender": {
        "employee_code": "EMP456",
        "name": "Jane Smith"
      },
      "tag": "image",
      "image": {
        "content": "https://example.com/image.jpg"
      },
      "created_at": 1615456890
    }
  ],
  "has_more": true,
  "next_cursor": "next_page_cursor"
}

send_message_to_group_chat

Send a message to a group chat which the bot has been added to.

Example (Text Message):

{
  "group_id": "group456",
  "message": {
    "tag": "text",
    "text": {
      "content": "Hello everyone! This is an announcement.",
      "format": 1
    }
  }
}

Example (Image Message):

{
  "group_id": "group456",
  "message": {
    "tag": "image",
    "image": {
      "content": "base64_encoded_image_data"
    }
  }
}

Response:

{
  "code": 0,
  "message_id": "msg123"
}

send_message_to_bot_user

Send a message to a user via the bot.

Example (Text Message):

{
  "employee_code": "EMP123",
  "message": {
    "tag": "text",
    "text": {
      "content": "Hi there! Just checking in.",
      "format": 1
    }
  }
}

Example (Interactive Message):

{
  "employee_code": "EMP123",
  "message": {
    "tag": "interactive_message",
    "interactive_message": {
      "elements": [
        {
          "tag": "header",
          "text": {
            "content": "Task Assignment",
            "tag": "plain_text"
          }
        },
        {
          "tag": "section",
          "text": {
            "content": "You have been assigned a new task.",
            "tag": "plain_text"
          }
        },
        {
          "tag": "action",
          "elements": [
            {
              "tag": "button",
              "text": {
                "content": "Accept",
                "tag": "plain_text"
              },
              "value": "accept_task"
            }
          ]
        }
      ]
    }
  }
}

Response:

{
  "code": 0,
  "message_id": "msg125"
}

Error Codes

All API responses include a code field that indicates the status of the request:

Code

Description

0

Success

2

Server error

5

Resource not found

8

Server error

100

App access token is expired or invalid

101

API is rejected due to rate limit control

102

Request body contains invalid input

103

App permission denied

104

Bot capability is not turned on

105

App is not online

Auth-specific errors

Code

Description

1000

App Secret is invalid

2000

Single Sign-On Token is expired or invalid

2001

User is not an employee of the current company

2002

Token belongs to another app

2003

Cursor invalid

2004

Cursor expired

User-specific errors

Code

Description

3000

User not found with the current email

3001

User not found with the current code

3002

User is not a subscriber of the bot

3003

User is not signed in to SeaTalk

3004

Invalid custom field name

Message-specific errors

Code

Description

4000

Message type is invalid

4001

Message exceeds the maximum length

4002

Message sending failed

4003

Message cannot be empty

4004

Fail to fetch the quoted message due to SeaTalk's internal error

4005

The quoted message cannot be found

4009

Message cannot be found via the message id provided

4010

The thread cannot be found

4011

Mention everyone (@all) is not allowed in thread replies

4012

No permission to update this message

App-specific errors

Code

Description

5000

appID mismatch

5001

linkID expired

5002

App not released yet

5003

App link amount has reached the upper limit

Group chat errors

Code

Description

7000

Group chat not found with the current code

7001

Bot is not a member of the group chat

License

MIT

Available Tools

11 tools
check_employee_existenceA

Verify whether employees exist in the organization via SeaTalk ID

Inputs: id (required).

get_chat_historyB

Obtain the group chat history (messages sent within 7 days)

Inputs: group_id (required), cursor, page_size.

get_employee_code_with_emailB

Get an employee's code by email address

Inputs: emails (required).

get_employee_profileB

Get an employee's profile by employee ID

Inputs: employee_code (required).

get_group_infoC

Get information about a group chat, including member list

Inputs: group_id (required), cursor, page_size.

get_joined_group_chat_listB

Obtain group chats the bot joined

Inputs: cursor, page_size.

get_message_by_message_idA

Retrieve a message by its message ID within a group chat thread

Inputs: message_id (required).

get_thread_by_thread_idC

Retrieve all messages within a thread of a group chat

Inputs: group_id (required), thread_id (required), cursor, page_size.

get_user_language_preferenceC

Get a user's language preference

Inputs: employee_code (required).

send_message_to_bot_userC

Send a message to a user via the bot

Inputs: message (required), employee_code (required).

send_message_to_group_chatC

Send a message to a group chat which the bot has been added to

Inputs: message (required), group_id (required), thread_id, quoted_message_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.5/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of the SeaTalk domain: employee verification, profile retrieval, various chat operations, and language preference. No two tools have overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., check_employee_existence, get_chat_history, send_message_to_group_chat), making them predictable and easy to navigate.

    Tool Count5/5

    11 tools cover the core functionalities of an employee and group chat server without being excessive or insufficient. Each tool serves a clear role.

    Completeness4/5

    The tool surface covers essential operations like employee lookup and chat retrieval/messaging, but lacks update/delete capabilities for messages or group management, which are minor gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers