Mattermost Mcp Host

Mattermost MCP Host

A Mattermost integration that connects to Model Context Protocol (MCP) servers, leveraging a LangGraph-based AI agent to provide an intelligent interface for interacting with users and executing tools directly within Mattermost.

Demo

1. Github Agent in support channel - searches the existing issues and PRs and creates a new issue if not found

2. Search internet and post to a channel using Mattermost-MCP-server

Scroll below for full demo in YouTube

Features

• 🤖 Langgraph Agent Integration: Uses a LangGraph agent to understand user requests and orchestrate responses.
• 🔌 MCP Server Integration: Connects to multiple MCP servers defined in mcp-servers.json.
• 🛠️ Dynamic Tool Loading: Automatically discovers tools from connected MCP servers and makes them available to the AI agent. Converts MCP tools to langchain structured tools.
• 💬 Thread-Aware Conversations: Maintains conversational context within Mattermost threads for coherent interactions.
• 🔄 Intelligent Tool Use: The AI agent can decide when to use available tools (including chaining multiple calls) to fulfill user requests.
• 🔍 MCP Capability Discovery: Allows users to list available servers, tools, resources, and prompts via direct commands.
• #️⃣ Direct Command Interface: Interact directly with MCP servers using a command prefix (default: #).

Overview

The integration works as follows:

1. Mattermost Connection (mattermost_client.py): Connects to the Mattermost server via API and WebSocket to listen for messages in a specified channel.
2. MCP Connections (mcp_client.py): Establishes connections (primarily stdio) to each MCP server defined in src/mattermost_mcp_host/mcp-servers.json. It discovers available tools on each server.
3. Agent Initialization (agent/llm_agent.py): A LangGraphAgent is created, configured with the chosen LLM provider and the dynamically loaded tools from all connected MCP servers.
4. Message Handling (main.py):

• If a message starts with the command prefix (#), it's parsed as a direct command to list servers/tools or call a specific tool via the corresponding MCPClient.
• Otherwise, the message (along with thread history) is passed to the LangGraphAgent.

1. Agent Execution: The agent processes the request, potentially calling one or more MCP tools via the MCPClient instances, and generates a response.
2. Response Delivery: The final response from the agent or command execution is posted back to the appropriate Mattermost channel/thread.

Setup

1. Clone the repository:

``bash git clone cd mattermost-mcp-host ``

1. Install:

• Using uv (recommended):

```bash # Install uv if you don't have it yet # curl -LsSf https://astral.sh/uv/install.sh | sh

# Activate venv source .venv/bin/activate

# Install the package with uv uv sync

# To install dev dependencies uv sync --dev --all-extras ```

1. Configure Environment (.env file):

Copy the .env.example and fill in the values or Create a .env file in the project root (or set environment variables): ```env # Mattermost Details MATTERMOSTURL=http://your-mattermost-url MATTERMOSTTOKEN=your-bot-token # Needs permissions to post, read channel, etc. MATTERMOSTTEAMNAME=your-team-name MATTERMOSTCHANNELNAME=your-channel-name # Channel for the bot to listen in # MATTERMOSTCHANNELID= # Optional: Auto-detected if name is provided

# LLM Configuration (Azure OpenAI is default) DEFAULTPROVIDER=azure AZUREOPENAIENDPOINT=your-azure-endpoint AZUREOPENAIAPIKEY=your-azure-api-key AZUREOPENAIDEPLOYMENT=your-deployment-name # e.g., gpt-4o # AZUREOPENAIAPI_VERSION= # Optional, defaults provided

# Optional: Other providers (install with [all] extra) # OPENAIAPIKEY=... # ANTHROPICAPIKEY=... # GOOGLEAPIKEY=...

# Command Prefix COMMAND_PREFIX=# `` See .env.example` for more options.

1. Configure MCP Servers:

Edit src/mattermost_mcp_host/mcp-servers.json to define the MCP servers you want to connect to. See src/mattermost_mcp_host/mcp-servers-example.json. Depending on the server configuration, you might npx, uvx, docker installed in your system and in path.

1. Start the Integration:

``bash mattermost-mcp-host ``

Prerequisites

• Python 3.13.1+
• uv package manager
• Mattermost server instance
• Mattermost Bot Account with API token
• Access to a LLM API (Azure OpenAI)

Optional

• One or more MCP servers configured in mcp-servers.json
• Tavily web search requires TAVILY_API_KEY in .env file

Usage in Mattermost

Once the integration is running and connected:

1. Direct Chat: Simply chat in the configured channel or with the bot. The AI agent will respond, using tools as needed. It maintains context within message threads.
2. Direct Commands: Use the command prefix (default #) for specific actions:

• #help - Display help information.
• #servers - List configured and connected MCP servers.
• # tools - List available tools for ``.
• # call - Call ` on ` with arguments provided as a JSON string.
• Example: #my-server call echo '{"message": "Hello MCP!"}'
• # resources - List available resources for ``.
• # prompts - List available prompts for ``.

Next Steps

• ⚙️ Configurable LLM Backend: Supports multiple AI providers (Azure OpenAI default, OpenAI, Anthropic Claude, Google Gemini) via environment variables.

Mattermost Setup

1. Create a Bot Account

• Go to Integrations > Bot Accounts > Add Bot Account
• Give it a name and description
• Save the access token in the .env file

1. Required Bot Permissions

• post_all
• create_post
• read_channel
• createdirectchannel
• read_user

1. Add Bot to Team/Channel

• Invite the bot to your team
• Add bot to desired channels

Troubleshooting

1. Connection Issues

• Verify Mattermost server is running
• Check bot token permissions
• Ensure correct team/channel names

1. AI Provider Issues

• Validate API keys
• Check API quotas and limits
• Verify network access to API endpoints

1. MCP Server Issues

• Check server logs
• Verify server configurations
• Ensure required dependencies are installed and env variables are defined

Demos

Create issue via chat using Github MCP server

(in YouTube)

[](https://youtu.be/s6CZY81DRrU)

Contributing

Please feel free to open a PR.

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jagan-shanmugam
• Source: jagan-shanmugam/mattermost-mcp-host
• License: MIT

Install and usage instructions live in the source repository linked above.