NosytLabs / KickMCP Public

Notifications
Fork0
Star 1

Kick API MCP

MIT license

1 star0 forksBranches Tags Activity

Star

Notifications

main

BranchesTags

Go to file

Code

Name	Name	Last commit message	Last commit date
1 Commit
scripts	scripts
src	src
.dockerignore	.dockerignore
.env.example	.env.example
.eslintrc.json	.eslintrc.json
.gitignore	.gitignore
.prettierrc	.prettierrc
Dockerfile	Dockerfile
LICENSE	LICENSE
README.md	README.md
package-lock.json	package-lock.json
package.json	package.json
smithery.yaml	smithery.yaml
tsconfig.json	tsconfig.json
View all files

Repository files navigation

🚀 Kick MCP Server

A high-performance Model Context Protocol (MCP) server implementation for the Kick streaming platform API. This server provides a robust, secure, and standardized interface for AI models to interact with Kick's services.

License: MIT MCP Version Node.js Version Docker Compatible

📋 Table of Contents

Features
MCP Protocol
Use Cases
Quick Start Guide
Authentication
API Documentation
- Authentication Methods
- User Methods
- Chat Methods
- Channel Methods
- Stream Methods
- Search and Discovery Methods
- Clip Methods
Configuration
Security Features
Monitoring
Performance Optimizations
Debugging
Contributing
License
Acknowledgments

🌟 Features

Core Features

🔐 Secure OAuth 2.0 Authentication
- Automatic token refresh
- Scope-based authorization
- JWT validation
🔄 Real-time Communication
- JSON-RPC over stdin/stdout
- Automatic reconnection
- Session management
🛡️ Enterprise-grade Security
- Request validation
- Rate limiting
- Error handling
📊 Advanced Monitoring
- Health checks
- Performance tracking
- CPU and memory monitoring
💾 Caching & Performance
- Smart in-memory caching
- Request optimization
- Minimal dependencies

MCP Best Practices

✅ Standardized error responses
✅ Consistent method naming
✅ Proper parameter validation
✅ Comprehensive logging
✅ Automatic retries
✅ Rate limit handling

🔄 MCP Protocol

The server implements the Model Context Protocol (MCP) specification, providing a standardized interface for AI models to interact with Kick's services:

Key Components

JSON-RPC Communication: All interactions use JSON-RPC 2.0 over stdin/stdout
Tool Definitions: Comprehensive set of tools for Kick API interaction
Error Handling: Standardized error responses and retry logic
Authentication: Secure OAuth 2.0 flow for API access

Protocol Flow

Model sends JSON-RPC request via stdin
Server processes request and calls Kick API
Server sends JSON-RPC response via stdout
Model receives response and continues processing

Example Protocol Exchange

// Model Request { "jsonrpc": "2.0", "method": "getUserProfile", "params": { "access_token": "user_access_token" }, "id": 1 }

// Server Response { "jsonrpc": "2.0", "result": { "username": "example_user", "profile_picture": "https://example.com/avatar.jpg", "followers": 1000 }, "id": 1 }

💡 Use Cases

This MCP server enables a wide range of applications with the Kick API. Here are some practical use cases:

Chatbots and Moderation

AI-Powered Chat Assistant: Create smart chatbots that can answer viewer questions and provide stream information.
Auto-Moderation: Build custom moderation tools that use AI to detect inappropriate content and take action automatically.
Language Translation: Implement real-time chat translation to make your streams accessible to international audiences.

Stream Analytics

Viewer Engagement Tracking: Analyze chat activity, viewer count trends, and subscription rates over time.
Performance Dashboard: Build custom dashboards showing real-time metrics about your stream's performance.
Competitor Analysis: Track top-performing streams in your category to identify successful content strategies.

Community Building

Discord Integration: Sync channel subscriptions and roles between Kick and Discord communities.
Custom Alerts: Create personalized notifications when favorite streamers go live or for special events.
Reward Systems: Implement custom loyalty programs that track viewer engagement across multiple streams.

Stream Enhancement

Interactive Overlays: Create dynamic stream overlays that respond to chat commands or channel events.
Prediction Games: Build custom prediction systems with automated result tracking.
Multi-Stream Management: Manage multiple channels from a single dashboard for easier content coordination.

Content Creation

Highlight Clips: Automatically create clips of key moments based on chat activity or stream markers.
Social Media Integration: Auto-post stream notifications, clips, or highlights to social media platforms.
Content Scheduling: Schedule and manage upcoming streams with automatic announcements.

Revenue Optimization

Subscription Analytics: Track subscription patterns to identify optimal streaming times and content.
Gift Tracking: Monitor gift trends to better understand audience generosity patterns.
Advertiser Dashboard: Create metrics reports for potential channel sponsors and advertisers.

Each of these use cases can be implemented using the MCP server's comprehensive set of tools for interacting with the Kick API in a secure, standardized way.

🚀 Quick Start Guide

If you're new to programming, APIs, or Kick, don't worry! This guide will walk you through everything step by step, just like following a recipe.

🛠️ What You'll Need (Like Ingredients for a Recipe)

Node.js (version 18 or higher)
- Think of this as the "kitchen" where your app will run
- Download from nodejs.org (click the big green button)
- To check if it's installed, open your terminal and type:
  node --version
  You should see a number like v18.0.0 or higher
Git (to download the code)
- This is like a recipe book that keeps track of changes
- Download from git-scm.com
- To check if it's installed, type in your terminal:
  git --version
  You should see something like git version 2.x.x
A Kick API Key (Your Special Access Card)
- Go to Kick Developer Portal
- Click "Sign Up" if you don't have an account
- Click "Create New Application"
- Fill in the form (like registering for a new account)
- You'll get three important pieces:
  * client_id (like your username)
  * client_secret (like your password)
  * api_key (your main access card)

📥 Installation (Like Following a Recipe)

Option 1: Using Smithery (Easiest Way)

Copy and paste this into your terminal

npx -y @smithery/cli install @NosytLabs/kickmcp --client claude

This is like ordering a pre-made meal - everything is set up for you!

Option 2: Manual Installation (Like Cooking from Scratch)

1. Download the code (like getting the recipe)

git clone https://github.com/NosytLabs/KickMCP.git

2. Go into the project folder (like entering the kitchen)

cd KickMCP

3. Install everything needed (like gathering ingredients)

npm install

⚙️ Setting Up Your Environment (Like Prepping Your Kitchen)

Create your configuration file:

Copy the example file (like copying a recipe)

cp .env.example .env

Edit the .env file with your settings:

Your Kick API credentials (like your special ingredients)

KICK_API_KEY=your_api_key_here # Paste your API key here KICK_CLIENT_ID=your_client_id # Paste your client ID here KICK_CLIENT_SECRET=your_client_secret # Paste your client secret here

Basic server settings (like setting your oven temperature)

PORT=3000 # The door number for your app NODE_ENV=development # Set to 'production' when ready LOG_LEVEL=info # How much detail you want to see

Webhook Configuration

WEBHOOK_URL=https://your-domain.com/webhooks/kick # Your public webhook endpoint WEBHOOK_SECRET=your_webhook_secret # Secret for webhook validation

🚀 Starting the Server (Like Turning On Your Oven)

For AI Integration (MCP Mode)

npm run mcp

This is like setting up a robot chef that follows instructions.

For Web/App Integration (HTTP Mode)

npm start

This is like opening a restaurant where people can visit.

For Development (with Auto-Restart)

npm run dev

This is like having a helper who automatically fixes mistakes.

✅ Testing Your Setup (Like Tasting Your Food)

Quick Health Check

curl http://localhost:3000/health

If everything is working, you'll see a message like:

{ "status": "ok", "version": "1.0.0", "timestamp": "2023-04-15T12:34:56Z" }

🔧 Kick App Setup

To use this MCP server with Kick, you'll need to create a Kick app:

Enable 2FA
- Go to your Kick Account Settings
- Enable Two-Factor Authentication (2FA)
- This is required to access the developer tools
Create Your Kick App
- Go to your Account Settings
- Navigate to the Developer tab
- Click "Create New App"
- Fill in the following details:
  * Name: "Kick MCP Server"
  * Description: "A Model Context Protocol server for Kick API integration"
  * Redirect URL: http://localhost:3000/auth/callback
- Click "Create App"
- Save your client_id and client_secret

Configure Your Environment

Copy .env.example to .env
Update the following variables:

KICK_API_KEY=your_api_key_here  
KICK_CLIENT_ID=your_client_id_here  
KICK_CLIENT_SECRET=your_client_secret_here  
KICK_REDIRECT_URI=http://localhost:3000/auth/callback

Verify Your Setup
- Start the server: npm run mcp
- Test authentication:
  {
  "jsonrpc": "2.0",
  "method": "getOAuthUrl",
  "params": {
  "client_id": "your_client_id",
  "redirect_uri": "http://localhost:3000/auth/callback",
  "scope": "user:read channel:read"
  },
  "id": 1
  }

🔐 Authentication Made Simple

🔑 What is Authentication?

Think of authentication like a special key card system:

Your app needs a key card (access token) to enter Kick's building
The key card has different access levels (scopes)
The key card expires after a while and needs to be renewed

📝 Getting Your First Access Token (Like Getting Your Key Card)

Get Your Developer Credentials
- Go to Kick Developer Portal
- Click "Create New Application"
- Fill in the form:
  * Name: Your app's name
  * Description: What your app does
  * Website: Your app's website
- You'll get three important pieces:
  * client_id (like your employee ID)
  * client_secret (like your PIN number)
  * api_key (your main access card)
Get an OAuth URL (Like Requesting Access)
{
"jsonrpc": "2.0",
"method": "getOAuthUrl",
"params": {
"client_id": "your_client_id",
"redirect_uri": "https://your-app.com/callback",
"scope": "user:read channel:read"
},
"id": 1
}
| Parameter | What it is | Example | Why it's needed |
| ------------- | ----------------------- | ----------------------------- | ----------------------------------------- |
| client_id | Your app's ID | abc123def456 | So Kick knows which app is asking |
| redirect_uri | Where to go after login | https://your-app.com/callback | Where to send the user after they approve |
| scope | What your app can do | user:read channel:read | What permissions your app needs |
Get Your Access Token (Like Getting Your Key Card)
{
"jsonrpc": "2.0",
"method": "getAccessToken",
"params": {
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"code": "code_from_kick",
"redirect_uri": "https://your-app.com/callback"
},
"id": 2
}
| Parameter | What it is | Example | Why it's needed |
| -------------- | ----------------- | ----------------------------- | ------------------------------- |
| client_id | Your app's ID | abc123def456 | To identify your app |
| client_secret | Your app's secret | xyz789uvw012 | To prove it's really your app |
| code | Temporary code | auth_code_123 | The code Kick gave you |
| redirect_uri | Same as before | https://your-app.com/callback | Must match what you used before |

🔄 Using Your Access Token (Like Using Your Key Card)

Make Your First API Call

This is like showing your key card to enter

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://kick.com/api/v2/user/profile 2. What to Do When Your Token Expires (Like Renewing Your Key Card)
{
"jsonrpc": "2.0",
"method": "refreshAccessToken",
"params": {
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"refresh_token": "your_refresh_token"
},
"id": 3
}

🔍 Understanding Scopes (Like Access Levels)

Scopes are like different areas your key card can access:

Scope	What it lets you do	Example Use	Like Having Access To...
user:read	See user information	Show user profile	The user directory
channel:read	See channel details	Display channel info	The channel listings
channel:write	Change channel settings	Update stream title	The control room
chat:write	Send chat messages	Create chat bot	The chat system
streamkey:read	Get stream URLs	Show stream link	The streaming room
events:subscribe	Get notifications	Alert when stream starts	The notification system

❓ Common Questions (Like FAQ)

How long do tokens last?
- Access tokens: Usually 1 hour (like a temporary pass)
- Refresh tokens: Much longer (like a permanent ID card)
What if my token stops working?
- Try refreshing it (like renewing your pass)
- If that doesn't work, get a new one (like getting a new ID card)
How do I know what scopes I need?
- Start with just what you need (like only requesting access to the rooms you'll use)
- Add more as your app grows (like requesting access to more rooms later)
- Check the API documentation for required scopes (like reading the building rules)
What if I make a mistake?
- Check the error message (like reading the sign on the door)
- Make sure your credentials are correct (like checking your ID card)
- Try the steps again (like going through the process again)

📚 API Documentation

Authentication Methods

Method	Description	Parameters	Notes
getOAuthUrl	Get OAuth authorization URL	client_id: Your application IDredirect_uri: URL to redirect after authscope: Space-separated scopesstate: Random state stringcode_challenge: Code challengecode_challenge_method: Code challenge method	Returns a URL that your users should visit to authorize your app
getAccessToken	Exchange code for token	client_id: Your application IDclient_secret: Your secret keycode: Auth code from redirectredirect_uri: Redirect URIcode_verifier: Code verifier	Exchange the temporary code for a long-lived access token
refreshAccessToken	Refresh expired token	client_id: Your application IDclient_secret: Your secret keyrefresh_token: Token for refreshing	Use when access_token expires to get a new one
validateToken	Validate access token	access_token: Token to validate	Check if a token is still valid and get its associated scopes
revokeToken	Revoke access token	access_token: Token to revoke	Immediately invalidate a token for security
getAppAccessToken	Get app access token	client_id: Your application IDclient_secret: Your secret key	Generate app access token for public data

Example: Getting an OAuth URL

{ "jsonrpc": "2.0", "method": "getOAuthUrl", "params": { "client_id": "your_client_id", "redirect_uri": "https://your-app.com/callback", "scope": "user:read channel:read", "state": "random_state_string", "code_challenge": "your_code_challenge", "code_challenge_method": "S256" }, "id": 1 }

Example: Exchanging a code for a token

{ "jsonrpc": "2.0", "method": "getAccessToken", "params": { "client_id": "your_client_id", "client_secret": "your_client_secret", "code": "authorization_code_from_redirect", "redirect_uri": "https://your-app.com/callback", "code_verifier": "your_code_verifier" }, "id": 2 }

User Methods

Method	Description	Parameters	Notes
getUserProfile	Get user profile	access_token: User's access token	Returns the authenticated user's profile
updateUserProfile	Update user profile	access_token: User's access tokendata: Object with profile fields	Update user profile information
getUserSubscriptions	Get subscriptions	access_token: User's access token	List channels the user is subscribed to
getUserEmotes	Get user emotes	access_token: User's access token	Emotes the user has access to
getUserBadges	Get user badges	access_token: User's access token	Badges earned by the user
getUserFollows	Get followed channels	access_token: User's access token	Channels the user follows
getUserBlockedUsers	Get blocked users	access_token: User's access token	Users blocked by this user
getUserClips	Get user clips	access_token: User's access token	Clips created by the user
getUserVideos	Get user videos	access_token: User's access token	Videos uploaded by the user
getUserHighlights	Get user highlights	access_token: User's access token	Stream highlights
getUserScheduledStreams	Get scheduled streams	access_token: User's access token	Upcoming streams
getUserNotifications	Get notifications	access_token: User's access token	User's notification feed
getUserWallet	Get wallet info	access_token: User's access token	User's balance and transactions
getUserGifts	Get gift history	access_token: User's access token	Gifts sent and received

Example: Getting a user profile

{ "jsonrpc": "2.0", "method": "getUserProfile", "params": { "access_token": "user_access_token" }, "id": 3 }

Chat Methods

Method	Description	Parameters	Notes
getChatMessages	Get chat messages	access_token: User's access tokenchannel_id: Channel ID	Recent messages in the channel
sendChatMessage	Send chat message	access_token: User's access tokenchannel_id: Channel IDmessage: Message content	Requires chat:write scope
getChatSettings	Get chat settings	access_token: User's access tokenchannel_id: Channel ID	Chat configuration
banUser	Ban user from chat	access_token: User's access tokenchannel_id: Channel IDuser_id: User to ban	Requires moderator privileges
unbanUser	Unban user from chat	access_token: User's access tokenchannel_id: Channel IDuser_id: User to unban	Requires moderator privileges
timeoutUser	Timeout user	access_token: User's access tokenchannel_id: Channel IDuser_id: User to timeoutduration: Timeout duration in seconds	Requires moderator privileges
deleteMessage	Delete chat message	access_token: User's access tokenchannel_id: Channel IDmessage_id: Message to delete	Requires moderator privileges
clearChat	Clear all chat messages	access_token: User's access tokenchannel_id: Channel ID	Requires moderator privileges
getChatUserInfo	Get chat user info	access_token: User's access tokenchannel_id: Channel IDuser_id: User to query	User's chat privileges

Example: Sending a chat message

{ "jsonrpc": "2.0", "method": "sendChatMessage", "params": { "access_token": "user_access_token", "channel_id": "123456", "message": "Hello, Kick chat!" }, "id": 4 }

Channel Methods

Method	Description	Parameters	Notes
getChannelInfo	Get channel info	access_token: User's access tokenchannel_id: Channel ID	Basic channel information
getChannelFollowers	Get followers	access_token: User's access tokenchannel_id: Channel ID	Users following the channel
getChannelSubscribers	Get subscribers	access_token: User's access tokenchannel_id: Channel ID	Requires channel ownership
getChannelEmotes	Get channel emotes	access_token: User's access tokenchannel_id: Channel ID	Custom channel emotes
getChannelBadges	Get channel badges	access_token: User's access tokenchannel_id: Channel ID	Loyalty and subscriber badges
getChannelModerators	Get moderators	access_token: User's access tokenchannel_id: Channel ID	Requires channel ownership
getChannelBans	Get banned users	access_token: User's access tokenchannel_id: Channel ID	Requires moderator privileges
getChannelVips	Get VIP users	access_token: User's access tokenchannel_id: Channel ID	Users with VIP status
getChannelClips	Get channel clips	access_token: User's access tokenchannel_id: Channel ID	Popular clips from channel
getChannelVideos	Get channel videos	access_token: User's access tokenchannel_id: Channel ID	VODs and uploads
getChannelHighlights	Get highlights	access_token: User's access tokenchannel_id: Channel ID	Highlighted moments
getChannelScheduledStreams	Get schedule	access_token: User's access tokenchannel_id: Channel ID	Upcoming streams
getChannelChatRules	Get chat rules	access_token: User's access tokenchannel_id: Channel ID	Channel's chat guidelines
getChannelChatCommands	Get commands	access_token: User's access tokenchannel_id: Channel ID	Custom chat commands
getChannelCategories	Get categories	access_token: User's access tokenchannel_id: Channel ID	Categories used by channel
getChannelTags	Get channel tags	access_token: User's access tokenchannel_id: Channel ID	Tags used by the channel
getChannelGifts	Get gift history	access_token: User's access tokenchannel_id: Channel ID	Gift transactions
getChannelRaids	Get raid history	access_token: User's access tokenchannel_id: Channel ID	Incoming/outgoing raids
getChannelHosts	Get host history	access_token: User's access tokenchannel_id: Channel ID	Host events

Example: Getting channel information

{ "jsonrpc": "2.0", "method": "getChannelInfo", "params": { "access_token": "user_access_token", "channel_id": "123456" }, "id": 5 }

Stream Methods

Method	Description	Parameters	Notes
startStream	Start streaming	access_token: User's access tokenchannel_id: Channel ID	Requires channel:write scope
endStream	End stream	access_token: User's access tokenchannel_id: Channel ID	Requires channel:write scope
updateStreamInfo	Update stream info	access_token: User's access tokenchannel_id: Channel IDdata: Stream metadata	Update title, category, etc.
updateStreamSettings	Update settings	access_token: User's access tokenchannel_id: Channel IDdata: Settings object	Technical stream settings
getStreamInfo	Get stream info	access_token: User's access tokenchannel_id: Channel ID	Current stream details
getStreamViewers	Get viewers	access_token: User's access tokenchannel_id: Channel ID	Current viewer count and list
getStreamCategories	Get categories	access_token: User's access tokenchannel_id: Channel ID	Categories of current stream
getStreamTags	Get stream tags	access_token: User's access tokenchannel_id: Channel ID	Tags of current stream
getStreamStats	Get statistics	access_token: User's access tokenchannel_id: Channel ID	Performance metrics
createPoll	Create poll	access_token: User's access tokenchannel_id: Channel IDtitle: Poll titleoptions: Array of optionsduration: Duration in seconds	Start a new viewer poll
endPoll	End active poll	access_token: User's access tokenchannel_id: Channel IDpoll_id: Poll to end	End poll early
createPrediction	Create prediction	access_token: User's access tokenchannel_id: Channel IDtitle: Prediction titleoptions: Array of outcomesduration: Duration in seconds	Start a channel prediction
endPrediction	End prediction	access_token: User's access tokenchannel_id: Channel IDprediction_id: Prediction ID	End prediction early

📄 Configuration

The server configuration is managed through environment variables and a configuration file.

Environment Variables

PORT: The port on which the server runs
NODE_ENV: The environment in which the server is running (e.g., development, production)
LOG_LEVEL: The level of detail in server logs
KICK_API_KEY: Your Kick API key
KICK_CLIENT_ID: Your Kick client ID
KICK_CLIENT_SECRET: Your Kick client secret
WEBHOOK_URL: Your webhook URL
WEBHOOK_SECRET: Your webhook secret

Configuration File

The configuration file is located at .env.

🛡️ Security Features

The server implements several security features to protect against common threats:

Rate Limiting: Prevents abuse by limiting the number of requests from a single IP address.
Request Validation: Ensures that all requests are valid and authorized.
Error Handling: Provides standardized error responses and retry logic.
Authentication: Uses OAuth 2.0 for secure API access.

📊 Monitoring

The server includes built-in monitoring capabilities to help you keep track of its performance and health:

Health Checks: Regularly checks the server's health.
Performance Tracking: Tracks server performance metrics.
CPU and Memory Monitoring: Monitors the server's CPU and memory usage.

🚀 Performance Optimizations

The server is designed to be highly performant and efficient:

Smart In-Memory Caching: Reduces the number of database queries.
Request Optimization: Optimizes server response times.
Minimal Dependencies: Reduces the server's resource footprint.

🔍 Debugging

The server includes built-in debugging capabilities to help you diagnose and fix issues:

Logging: Detailed server logs for troubleshooting.
Error Handling: Provides standardized error responses and retry logic.

🤝 Contributing

We welcome contributions from the community! If you're interested in contributing to the project, please follow these steps:

Fork the Repository: Fork the repository on GitHub.
Create a New Branch: Create a new branch for your changes.
Make Your Changes: Make your changes in the new branch.
Test Your Changes: Ensure that your changes work as expected.
Submit a Pull Request: Submit a pull request to the main repository.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more information.

🎉 Acknowledgments

We would like to thank the following individuals and organizations for their contributions to this project:

Smithery: For providing the infrastructure and tools to run the server.
Kick: For providing the platform and API.
Node.js: For providing the runtime environment.
Docker: For providing the containerization platform.

Thank you for using Kick MCP Server! We hope you find it useful and enjoyable.

About