Mattermost MCP Host

1# Mattermost MCP Host
2 
3A 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.
4 
5![Version](https://img.shields.io/badge/version-0.1.0-blue)
6![Python](https://img.shields.io/badge/python-3.13.1%2B-blue)
7![License](https://img.shields.io/badge/license-MIT-green)
8![Package Manager](https://img.shields.io/badge/package%20manager-uv-purple)
9 
10 
11 
12## Demo
13 
14### 1. Github Agent in support channel - searches the existing issues and PRs and creates a new issue if not found
15![Description of your GIF](./demo/demo-3.gif)   
16 
17 
18### 2. Search internet and post to a channel using Mattermost-MCP-server
19![Description of your GIF](./demo/demo-2.gif)
20 
21#### Scroll below for full demo in YouTube
22 
23## Features
24 
25- 🤖 **Langgraph Agent Integration**: Uses a LangGraph agent to understand user requests and orchestrate responses.
26- 🔌 **MCP Server Integration**: Connects to multiple MCP servers defined in `mcp-servers.json`.
27- 🛠️ **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.
28- 💬 **Thread-Aware Conversations**: Maintains conversational context within Mattermost threads for coherent interactions.
29- 🔄 **Intelligent Tool Use**: The AI agent can decide when to use available tools (including chaining multiple calls) to fulfill user requests.
30- 🔍 **MCP Capability Discovery**: Allows users to list available servers, tools, resources, and prompts via direct commands.
31- #️⃣ **Direct Command Interface**: Interact directly with MCP servers using a command prefix (default: `#`).
32 
33 
34## Overview
35 
36The integration works as follows:
37 
381.  **Mattermost Connection (`mattermost_client.py`)**: Connects to the Mattermost server via API and WebSocket to listen for messages in a specified channel.
392.  **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.
403.  **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.
414.  **Message Handling (`main.py`)**:
42    *   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`.
43    *   Otherwise, the message (along with thread history) is passed to the `LangGraphAgent`.
445.  **Agent Execution**: The agent processes the request, potentially calling one or more MCP tools via the `MCPClient` instances, and generates a response.
456.  **Response Delivery**: The final response from the agent or command execution is posted back to the appropriate Mattermost channel/thread.
46 
47## Setup
481.  **Clone the repository:**
49    ```bash
50    git clone <repository-url>
51    cd mattermost-mcp-host
52    ```
53 
542.  **Install:**
55    *   Using uv (recommended):
56        ```bash
57        # Install uv if you don't have it yet
58        # curl -LsSf https://astral.sh/uv/install.sh | sh 
59 
60        # Activate venv
61        source .venv/bin/activate
62        
63        # Install the package with uv
64        uv sync
65 
66        # To install dev dependencies
67        uv sync --dev --all-extras
68        ```
69 
703.  **Configure Environment (`.env` file):**
71    Copy the `.env.example` and fill in the values or
72    Create a `.env` file in the project root (or set environment variables):
73    ```env
74    # Mattermost Details
75    MATTERMOST_URL=http://your-mattermost-url
76    MATTERMOST_TOKEN=your-bot-token # Needs permissions to post, read channel, etc.
77    MATTERMOST_TEAM_NAME=your-team-name
78    MATTERMOST_CHANNEL_NAME=your-channel-name # Channel for the bot to listen in
79    # MATTERMOST_CHANNEL_ID= # Optional: Auto-detected if name is provided
80 
81    # LLM Configuration (Azure OpenAI is default)
82    DEFAULT_PROVIDER=azure
83    AZURE_OPENAI_ENDPOINT=your-azure-endpoint
84    AZURE_OPENAI_API_KEY=your-azure-api-key
85    AZURE_OPENAI_DEPLOYMENT=your-deployment-name # e.g., gpt-4o
86    # AZURE_OPENAI_API_VERSION= # Optional, defaults provided
87 
88    # Optional: Other providers (install with `[all]` extra)
89    # OPENAI_API_KEY=...
90    # ANTHROPIC_API_KEY=...
91    # GOOGLE_API_KEY=...
92 
93    # Command Prefix
94    COMMAND_PREFIX=# 
95    ```
96    See `.env.example` for more options.
97 
984.  **Configure MCP Servers:**
99    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`.
100    Depending on the server configuration, you might `npx`, `uvx`, `docker` installed in your system and in path.
101 
1025.  **Start the Integration:**
103    ```bash
104    mattermost-mcp-host
105    ```
106 
107 
108## Prerequisites
109 
110- Python 3.13.1+
111- uv package manager
112- Mattermost server instance
113- Mattermost Bot Account with API token
114- Access to a LLM API (Azure OpenAI)
115 
116### Optional
117- One or more MCP servers configured in `mcp-servers.json` 
118- Tavily web search requires `TAVILY_API_KEY` in `.env` file
119 
120 
121## Usage in Mattermost
122 
123Once the integration is running and connected:
124 
1251.  **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.
1262.  **Direct Commands:** Use the command prefix (default `#`) for specific actions:
127    *   `#help` - Display help information.
128    *   `#servers` - List configured and connected MCP servers.
129    *   `#<server_name> tools` - List available tools for `<server_name>`.
130    *   `#<server_name> call <tool_name> <json_arguments>` - Call `<tool_name>` on `<server_name>` with arguments provided as a JSON string.
131        *   Example: `#my-server call echo '{"message": "Hello MCP!"}'`
132    *   `#<server_name> resources` - List available resources for `<server_name>`.
133    *   `#<server_name> prompts` - List available prompts for `<server_name>`.
134 
135 
136 
137## Next Steps
138- ⚙️ **Configurable LLM Backend**: Supports multiple AI providers (Azure OpenAI default, OpenAI, Anthropic Claude, Google Gemini) via environment variables.
139 
140## Mattermost Setup
141 
1421. **Create a Bot Account**
143- Go to Integrations > Bot Accounts > Add Bot Account
144- Give it a name and description
145- Save the access token in the .env file
146 
1472. **Required Bot Permissions**
148- post_all
149- create_post
150- read_channel
151- create_direct_channel
152- read_user
153 
1543. **Add Bot to Team/Channel**
155- Invite the bot to your team
156- Add bot to desired channels
157 
158### Troubleshooting
159 
1601. **Connection Issues**
161- Verify Mattermost server is running
162- Check bot token permissions
163- Ensure correct team/channel names
164 
1652. **AI Provider Issues**
166- Validate API keys
167- Check API quotas and limits
168- Verify network access to API endpoints
169 
1703. **MCP Server Issues**
171- Check server logs
172- Verify server configurations
173- Ensure required dependencies are installed and env variables are defined
174 
175 
176## Demos
177 
178### Create issue via chat using Github MCP server
179![Description of your GIF](./demo/demo-1.gif)  
180 
181### (in YouTube)
182[![AI Agent in Action in Mattermost](./demo/supercut-thumbnail.png)](https://youtu.be/s6CZY81DRrU)
183 
184 
185## Contributing
186 
187Please feel free to open a PR.
188 
189## License
190 
191This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
192