Mattermost MCP Host is a Mattermost integration tool used to connect to Model Context Protocol (MCP) servers and, with the help of a LangGraph-based AI agent, interact with users and execute tools in Mattermost. The problem it solves is: allowing users to directly use the capabilities provided by various MCP servers in Mattermost teams and channels through chat or commands.
In terms of use cases, it is suitable for scenarios that need to integrate AI agents and external tools in a team communication environment, for example, letting a bot search existing issues and PRs in a support channel and create a new issue when none is found; or letting a bot search the internet and post the results to a channel.
Main capabilities include:
- LangGraph Agent integration: uses a LangGraph agent to understand user requests and organize responses.
- MCP server integration: connects to multiple MCP servers defined in mcp-servers.json.
- Dynamic tool loading: automatically discovers tools on connected MCP servers and converts them into LangChain structured tools for the AI agent to use.
- Thread-aware conversation: maintains conversation context in Mattermost message threads to ensure coherent interaction.
- Intelligent tool use: the AI agent can autonomously decide when to use available tools, including calling multiple tools in succession.
- MCP capability discovery: users can list available servers, tools, resources, and prompts through direct commands.
- Direct command interface: use a command prefix (default #) to interact directly with MCP servers.
- Configurable LLM backend: supports multiple AI providers through environment variables (default Azure OpenAI, also supports OpenAI, Anthropic Claude, Google Gemini).
How to use:
- Clone the repository: git clone <repository-url> then cd mattermost-mcp-host
- Install: the uv package manager is recommended. After installing uv, activate the virtual environment with source .venv/bin/activate, then run uv sync; to install development dependencies, use uv sync --dev --all-extras.
- Configure the environment: copy .env.example and fill it in, or create a .env file in the project root directory. You need to set the Mattermost URL, bot token, team name, channel name, and LLM configuration (such as DEFAULT_PROVIDER, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, AZURE_OPENAI_DEPLOYMENT, etc.). Optionally configure other providers (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY) and the command prefix COMMAND_PREFIX.
- Configure MCP servers: edit src/mattermost_mcp_host/mcp-servers.json, and you can refer to mcp-servers-example.json. Depending on the server configuration, you may need to install npx, uvx, docker on the system and add them to PATH.
- Start the integration: run mattermost-mcp-host.
- Prerequisites: uv package manager, a Mattermost server instance, a Mattermost bot account with an API token, an accessible LLM API (Azure OpenAI), and one or more MCP servers configured in mcp-servers.json. Using Tavily web search requires providing TAVILY_API_KEY in .env.
Usage in Mattermost:
- Direct chat: chat in the configured channel or with the bot, and the AI agent will use tools as needed and maintain context in the message thread.
- Direct commands (default prefix #):
- #help: display help information.
- #servers: list the configured and connected MCP servers.
- #<server_name> tools: list the available tools for the specified server.
- #<server_name> call <tool_name> <json_arguments>: call a tool on the specified server with JSON string arguments, for example #my-server call echo '{"message": "Hello MCP!"}'.
- #<server_name> resources: List the available resources of the specified server.
- #<server_name> prompts: List the available prompts of the specified server.
For Mattermost setup, you need to create a bot account (Integrations > Bot Accounts > Add Bot Account), save the access token to .env, and grant the required permissions (such as create_direct_channel), then add the bot to the team and channels.
Limitations and notes: operation depends on the Mattermost server, bot token, LLM API access, and configured MCP servers; some MCP servers may require tools such as npx, uvx, docker, etc. When troubleshooting, you can check the Mattermost connection, bot token permissions, team/channel names, API keys and quotas, network access, MCP server logs and configuration, dependencies, and environment variables. The project uses the MIT license; for more information, see the LICENSE file in the repository. The official sources do not provide specific information such as fees, pricing, or performance promises.
