@osiris-ai/slack-sdk

OAuth 2.0 Slack authenticator for building authenticated MCPs with Slack workspace integration.

Overview

The Slack SDK provides seamless OAuth 2.0 authentication for Slack in the Osiris ecosystem. Build powerful MCPs (Model Context Protocol) that can interact with Slack workspaces, channels, and users with enterprise-grade security and zero-configuration authentication.

Key Features:

• 🔐 Zero-config OAuth - No client credentials or setup required
• 🏢 Workspace Integration - Full access to Slack workspaces and teams
• 👥 User & Bot Scopes - Support for both workspace and user permissions
• 🔄 OAuth v2 - Latest Slack OAuth implementation
• 🛡️ Enterprise Security - Built on Osiris Hub authentication
• 📝 Full TypeScript - Complete type safety and IDE support

Installation

npm install @osiris-ai/slack-sdk @osiris-ai/sdk

Quick Start

Hub Authentication (Recommended)

The Slack authenticator works automatically through the Osiris Hub - no Slack OAuth app setup required.

import { createMcpServer, getAuthContext } from '@osiris-ai/sdk';
import { createSuccessResponse, createErrorResponse } from '../utils/types.js';
import { z } from 'zod';

await createMcpServer({
  name: 'slack-mcp',
  version: '1.0.0',
  auth: {
    useHub: true,
    hubConfig: {
      baseUrl: process.env.HUB_BASE_URL!,
      clientId: process.env.OAUTH_CLIENT_ID!,
      clientSecret: process.env.OAUTH_CLIENT_SECRET!,
    }
  },
  configure: (server) => {
    // Send Slack message
    server.tool(
      'send_slack_message',
      'Send a message to a Slack channel',
      {
        channel: z.string(),
        text: z.string(),
        username: z.string().optional()
      },
      async ({ channel, text, username }) => {
        try {
          const { token, context } = getAuthContext("osiris");
          if (!token || !context) {
            return createErrorResponse("User not authenticated");
          }

          const response = await fetch(`https://api.osirislabs.xyz/v1/hub/action/${context.deploymentId}/slack/chat.postMessage`, {
            method: 'POST',
            headers: {
              'Authorization': `Bearer ${token.access_token}`,
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              channel,
              text,
              username
            })
          });

          const result = await response.json();
          return createSuccessResponse('Message sent successfully', {
            timestamp: result.ts,
            channel: result.channel
          });
        } catch (error) {
          return createErrorResponse(error);
        }
      }
    );
  }
});

Available Slack Scopes

Configure your MCP to request specific Slack permissions:

All slack scopes are supported and they all need to prefixed with slack:

Local Authentication (Advanced)

For custom authentication flows or enterprise requirements:

import { SlackAuthenticator } from '@osiris-ai/slack-sdk';
import { createMcpServer } from '@osiris-ai/sdk';

const slackAuth = new SlackAuthenticator(
  ['channels:read', 'chat:write', 'users:read'],
  {
    clientId: process.env.SLACK_CLIENT_ID!,
    clientSecret: process.env.SLACK_CLIENT_SECRET!,
    redirectUri: 'http://localhost:3000/slack/callback'
  }
);

await createMcpServer({
  name: 'slack-mcp',
  version: '1.0.0',
  auth: {
    useHub: false,
    directAuth: {
      slack: slackAuth
    }
  },
  configure: (server) => {
    // Your Slack tools here
  }
});

API Reference

SlackAuthenticator

The main authenticator class for Slack OAuth integration.

class SlackAuthenticator extends OAuthAuthenticator<SlackCallbackParams, SlackTokenResponse>

Constructor

new SlackAuthenticator(allowedScopes: string[], config: SlackAuthenticatorConfig)

Parameters:

• allowedScopes: Array of Slack OAuth scopes your MCP requires
• config: Slack OAuth application configuration

Methods

getAuthenticationURL(scopes: string[], options: AuthenticationURLOptions): string

Generate Slack OAuth authorization URL with user scope support.

callback(params: SlackCallbackParams): Promise<SlackTokenResponse>

Handle OAuth callback and exchange code for tokens.

getUserInfo(accessToken: string): Promise<SlackUserInfo>

Get authenticated user information.

action(params: ActionParams, accessToken: string, refreshToken?: string): Promise<ActionResponse>

Execute Slack API actions with automatic error handling.

Note: Slack OAuth v2 provides both workspace and user tokens in the response.

Getting Started

1. Install the Osiris CLI:

   npm install -g @osiris-ai/cli

2. Set up authentication:

   npx @osiris-ai/cli register
   npx @osiris-ai/cli connect-auth

3. Create your Slack MCP:

   npx @osiris-ai/cli create-app my-slack-mcp

4. Add Slack integration:

   npm install @osiris-ai/slack-sdk

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• Documentation: https://docs.osirislabs.xyz
• GitHub Issues: https://github.com/fetcchx/osiris-ai/issues
• Discord Community: Join our Discord

License

MIT License - see LICENSE file for details.

Built with ❤️ by the Osiris Labs team.