mcp-slack-webhook by agentuse - MCP Server

MCP Slack Webhook Server

A Model Context Protocol (MCP) server that enables AI assistants to send messages to Slack via webhooks.

Features

Single flexible tool: send-message supports both simple text and rich Block Kit formatting
Environment-based configuration: Webhook URL configured via environment variable
Retry mechanism: Built-in retry logic for failed requests
Error handling: Comprehensive error handling and validation
TypeScript: Full type safety and modern ES modules

Installation

Using npx (Recommended)

No installation required - use directly with npx:

npx -y @agentuse/mcp-slack-webhook

From Source

cd packages/mcp-slack-webhook
pnpm install
pnpm run build

Configuration

Create a Slack app and enable incoming webhooks:
- Go to Slack API
- Create a new app or select existing one
- Navigate to "Incoming Webhooks" and activate it
- Create a webhook for your desired channel

Set up environment variables:

cp .env.example .env
# Edit .env and set your webhook URL

Set the SLACK_WEBHOOK_URL environment variable:

export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

Usage

Using as MCP Server

This server is designed to be used with MCP clients like Claude Code or other AI applications that support the Model Context Protocol.

With Claude Code

Build the server:
```
pnpm run build
```

Add to your Claude Code MCP configuration (usually ~/.config/claude-code/mcp.json):

Using npx (recommended):

{
  "mcpServers": {
    "slack-webhook": {
      "command": "npx",
      "args": ["-y", "@agentuse/mcp-slack-webhook"],
      "env": {
        "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "slack-webhook": {
      "command": "node",
      "args": ["/path/to/packages/mcp-slack-webhook/dist/index.js"],
      "env": {
        "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
      }
    }
  }
}

Restart Claude Code to load the MCP server

With Other MCP Clients

The server uses stdio transport and can be integrated with any MCP client:

# Set environment variable
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

# Run the server with npx
npx -y @agentuse/mcp-slack-webhook

Running Standalone (Development/Testing)

# Development mode
pnpm run dev

# Production mode
pnpm run build
pnpm start

Tool: `send-message`

Send messages to Slack with optional Block Kit formatting.

Parameters

text (required): The main message text. Used as fallback when blocks are provided.
blocks (optional): Array of Block Kit blocks for rich formatting.

Examples

Simple text message:

{
  "text": "Hello from MCP!"
}

Message with Block Kit formatting:

{
  "text": "System Alert",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "🚨 System Alert"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*CPU usage is high*\nServer: production-01\nUsage: 85%"
      }
    },
    {
      "type": "divider"
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Alert generated at <!date^1234567890^{date_short_pretty} at {time}|fallback>"
        }
      ]
    }
  ]
}

Message with fields:

{
  "text": "Deployment Status",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Deployment Complete*"
      },
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Environment:*\nProduction"
        },
        {
          "type": "mrkdwn",
          "text": "*Version:*\nv1.2.3"
        },
        {
          "type": "mrkdwn",
          "text": "*Status:*\n✅ Success"
        },
        {
          "type": "mrkdwn",
          "text": "*Duration:*\n2m 15s"
        }
      ]
    }
  ]
}

Common Block Types

header: Large header text
section: Text with optional fields
divider: Visual separator
context: Small, muted text (timestamps, metadata)

Error Handling

The server includes comprehensive error handling:

Invalid webhook URL: Validates URL format on startup
Network failures: Automatic retry with exponential backoff
Slack API errors: Detailed error messages returned
Invalid block format: Zod schema validation

Integration with Claude

This MCP server is designed to work seamlessly with AI assistants like Claude. The single send-message tool makes it easy for LLMs to:

Send simple notifications: {text: "Task completed"}
Create rich formatted alerts with blocks
Generate status reports with structured data

Available Tools

Once connected as an MCP server, this provides the following tool:

`send-message`

Purpose: Send messages to Slack via webhook
Parameters:
- text (required): Main message text
- blocks (optional): Block Kit blocks for rich formatting
Returns: Success confirmation or error details

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm run dev

# Build for production
pnpm run build

# Type checking
npx tsc --noEmit

Troubleshooting

Server won't start:

Check that SLACK_WEBHOOK_URL is set and valid
Ensure the webhook URL format: https://hooks.slack.com/services/...

Messages not appearing in Slack:

Verify webhook URL is correct
Check that the Slack app has permission to post to the target channel
Review server logs for error messages

Publishing to npm

For Maintainers

To publish a new version to npm:

Update version:

cd packages/mcp-slack-webhook
npm version patch  # or minor, major

Test the package:
```
pnpm run publish:dry-run
```
Login to npm (first time only):
```
npm login
```
Publish:
```
pnpm run publish:npm
```

Package Contents

The published package includes:

dist/ - Compiled JavaScript and TypeScript definitions
README.md - Documentation
LICENSE - MIT license
.env.example - Environment variable template

Source files and development dependencies are excluded via .npmignore.

License

MIT