instantKOM MCP Server

Model Context Protocol (MCP) Server for the instantKOM REST API. This server enables AI assistants like Claude to interact directly with the instantKOM API through standardized MCP tools.

Features

• Multi-Tenant Support: Configure different access levels for internal use and customers
• Scoped Access: Public, App, and Admin level tools based on tenant configuration
• 230+ Tools: Full CRUD coverage for Channels, Contacts, Messages, Newsletters, Bots, Flows, Analytics and more
• Type-Safe: Built with TypeScript for robust type checking
• Flexible Authentication: Bearer token authentication with configurable API keys

Distribution

• Public package (recommended for customers): npx -y @instantkom/mcp-server -- ships only public app tools (no admin/internal)
• Public repo: https://github.com/instantKOM/mcp-server (mirror of services/mcp-server/ from this monorepo)
• Internal: this folder; includes admin tools and tenant config

Quick Start

Installation

cd services/mcp-server
npm install

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env to select your tenant:

TENANT_ID=internal

3. (Optional) Configure tenants in src/config/tenants.json

Development

Run the server in development mode:

npm run dev

Build and Run

Build the TypeScript code:

npm run build

Run the compiled server:

npm start

Usage with Claude Code / Claude Desktop

Public package (customers)

{
  "mcpServers": {
    "instantkom": {
      "command": "npx",
      "args": ["-y", "@instantkom/mcp-server"],
      "env": {
        "INSTANTKOM_API_KEY": "ik_live_..."
      }
    }
  }
}

Local internal build (developers)

{
  "mcpServers": {
    "instantkom": {
      "command": "node",
      "args": [
        "/path/to/instantkom/services/mcp-server/dist/index.js"
      ],
      "env": {
        "TENANT_ID": "internal"
      }
    }
  }
}

For development with tsx (auto-reload):

{
  "mcpServers": {
    "instantkom": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/instantkom/services/mcp-server/src/index.ts"
      ],
      "env": {
        "TENANT_ID": "internal"
      }
    }
  }
}

After updating the configuration, restart Claude Code to load the MCP server.

Available Tools (overview)

The server ships 230+ tools covering all instantKOM resource types. The full list with parameters is documented at https://api.instantkom.app/api-docs for supported automation surfaces.

Public scope (no auth required)

• get_health

App scope (app + admin tenants)

| Category | Examples | Approx. count | |----------|----------|---------------| | Channels | list_channels, get_channel, create_channel, update_channel | 6 | | Contacts | list_contacts, get_contact, create_contact, ... | 5 | | Messages | list_messages, send_message, get_message, ... | 10 | | Broadcasts (Newsletters) | list_broadcasts, create_broadcast, send_broadcast, ... | 6 | | Bots & Flows | bot CRUD, flow nodes, flow edges | 38 | | Templates & Tags | template + tag CRUD, tag assignment | 21 | | Analytics | dashboard, broadcasts, contacts, messages KPIs | 5 | | Segmentation & QR | segmentation CRUD, QR codes, shortlinks | 13 | | Tickets, Webhooks, Polls, Events, Media, Custom Fields, Object Folders, ... | full CRUD | 100+ |

Admin scope (internal tenants only)

Includes platform-level analytics, user/team/billing operations, and feature flag management. Not part of the public package.

Multi-Tenant Configuration

Edit src/config/tenants.json to configure different tenants:

{
  "tenants": [
    {
      "id": "internal",
      "name": "instantKOM Internal",
      "apiUrl": "http://localhost:3002",
      "apiKey": "your-api-key",
      "scope": "admin"
    },
    {
      "id": "customer-readonly",
      "name": "Customer Read-Only",
      "apiUrl": "https://api.instantkom.app",
      "apiKey": "customer-api-key",
      "scope": "app",
      "enabledTools": ["list_*", "get_*"]
    }
  ]
}

Tenant Configuration Options

• id: Unique identifier (used in TENANT_ID env var)
• name: Display name
• apiUrl: REST API base URL
• apiKey: Bearer token for authentication
• scope: Access level (public, app, admin)
• enabledTools (optional): Whitelist specific tools (supports wildcards)

Environment Variables

• TENANT_ID: Tenant identifier (default: internal)
• API_URL: Override tenant's API URL
• API_KEY: Override tenant's API key
• LOG_LEVEL: Logging level (error, warn, info, debug)

Architecture

services/mcp-server/
├── src/
│   ├── index.ts              # MCP Server entry point
│   ├── config/
│   │   ├── config.ts         # Configuration loader
│   │   └── tenants.json      # Tenant configurations
│   ├── client/
│   │   └── api-client.ts     # HTTP client for REST API
│   ├── types/
│   │   └── index.ts          # TypeScript type definitions
│   └── tools/
│       ├── public/           # Public tools (health)
│       ├── app/              # App-level tools (channels, contacts, etc.)
│       └── admin/            # Admin-level tools (analytics)
├── package.json
├── tsconfig.json
└── README.md

Development

Adding New Tools

1. Create a new file in the appropriate directory (tools/public/, tools/app/, or tools/admin/)
2. Export tool definitions and handler functions
3. Import and register in src/index.ts
4. Add types to src/types/index.ts if needed

Example:

// tools/app/example.ts
export async function exampleTool(apiClient: ApiClient, args: any): Promise<any> {
  const response = await apiClient.get('/v1/example');
  return {
    content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }],
  };
}

export const exampleTools = [
  {
    name: 'example_tool',
    description: 'Example tool description',
    inputSchema: {
      type: 'object',
      properties: { /* ... */ },
      required: [],
    },
  },
];

Testing

The MCP server can be tested by:

1. Using Claude Code with the server configured
2. Testing API endpoints with the manual test script in services/api/manual-tests/
3. Checking logs in stderr (the server uses stdio for MCP communication)

Security

• API keys are passed as Bearer tokens
• Tenant configurations support scope-based access control
• Tool-level permissions via enabledTools whitelist
• All API communication over HTTPS in production

Troubleshooting

Server won't start:

• Check that the tenant ID exists in tenants.json
• Verify API key is correctly configured
• Ensure Node.js version is 18 or higher

Tools not appearing:

• Check tenant scope (public < app < admin)
• Verify enabledTools whitelist if configured
• Restart Claude Code after configuration changes

API errors:

• Verify API URL is correct and accessible
• Check API key is valid
• Review stderr logs for detailed error messages

License

MIT

Support

For issues and questions, please refer to the main instantKOM repository.