Skip to content
Back to search

mcp_chatbot

A chatbot implementation compatible with MCP (terminal / streamlit supported)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/keli-wen--mcp-chatbot/badge.svg)](/listings/keli-wen--mcp-chatbot)

HTML

<a href="/listings/keli-wen--mcp-chatbot"><img src="/api/listings/keli-wen--mcp-chatbot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Clone the repository:**

   git clone git@github.com:keli-wen/mcp_chatbot.git
   cd mcp_chatbot

2. **Set up a virtual environment (recommended):**

   cd folder

   # Install uv if you don't have it already
   pip install uv

   # Create a virtual environment and install dependencies
   uv venv .venv --python=3.10

   # Activate the virtual environment
   # For macOS/Linux
   source .venv/bin/activate
   # For Windows
   .venv\Scripts\activate

   # Deactivate the virtual environment
   deactivate

3. **Install dependencies:**

   pip install -r requirements.txt
   # or use uv for faster installation
   uv pip install -r requirements.txt

4. **Configure your environment:** - Copy the `.env.example` file to `.env`:

```bash cp .env.example .env ```

- Edit the `.env` file to add your Qwen API key (just for demo, you can use any LLM API key, remember to set the base_url and api_key in the .env file) and set the paths:

``` LLM_MODEL_NAME=your_llm_model_name_here LLM_BASE_URL=your_llm_base_url_here LLM_API_KEY=your_llm_api_key_here OLLAMA_MODEL_NAME=your_ollama_model_name_here OLLAMA_BASE_URL=your_ollama_base_url_here MARKDOWN_FOLDER_PATH=/path/to/your/markdown/folder RESULT_FOLDER_PATH=/path/to/your/result/folder ```

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 268 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCPChatbot Example
  2. ![MCP Chatbot](assets/mcp_chatbot_logo.png)
  3. This project demonstrates how to integrate the Model Context Protocol (MCP) with customized LLM (e.g. Qwen), creating a powerful chatbot that can interact with various tools through MCP servers. The implementation showcases the flexibility of MCP by enabling LLMs to use external tools seamlessly.
  4. > [!TIP]
  5. > For Chinese version, please refer to [README_ZH.md](README_ZH.md).
  6. ## Overview
  7. **Chatbot Streamlit Example**
  8. <img src="assets/mcp_chatbot_streamlit_demo_low.gif" width="800">
  9. **Workflow Tracer Example**
  10. <img src="assets/single_prompt_demo.png" width="800">
  11. - 🚩 Update (2025-04-11):
  12. - Added chatbot streamlit example.
  13. - 🚩 Update (2025-04-10):
  14. - More complex LLM response parsing, supporting multiple MCP tool calls and multiple chat iterations.
  15. - Added single prompt examples with both regular and streaming modes.
  16. - Added interactive terminal chatbot examples.
  17. This project includes:
  18. - Simple/Complex CLI chatbot interface
  19. - Integration with some builtin MCP Server like (Markdown processing tools)
  20. - Support for customized LLM (e.g. Qwen) and Ollama
  21. - Example scripts for single prompt processing in both regular and streaming modes
  22. - Interactive terminal chatbot with regular and streaming response modes
  23. ## Requirements
  24. - Python 3.10+
  25. - Dependencies (automatically installed via requirements):
  26. - python-dotenv
  27. - mcp[cli]
  28. - openai
  29. - colorama
  30. ## Installation
  31. 1. **Clone the repository:**
  32. ```bash
  33. git clone git@github.com:keli-wen/mcp_chatbot.git
  34. cd mcp_chatbot
  35. ```
  36. 2. **Set up a virtual environment (recommended):**
  37. ```bash
  38. cd folder
  39. # Install uv if you don't have it already
  40. pip install uv
  41. # Create a virtual environment and install dependencies
  42. uv venv .venv --python=3.10
  43. # Activate the virtual environment
  44. # For macOS/Linux
  45. source .venv/bin/activate
  46. # For Windows
  47. .venv\Scripts\activate
  48. # Deactivate the virtual environment
  49. deactivate
  50. ```
  51. 3. **Install dependencies:**
  52. ```bash
  53. pip install -r requirements.txt
  54. # or use uv for faster installation
  55. uv pip install -r requirements.txt
  56. ```
  57. 4. **Configure your environment:**
  58. - Copy the `.env.example` file to `.env`:
  59. ```bash
  60. cp .env.example .env
  61. ```
  62. - Edit the `.env` file to add your Qwen API key (just for demo, you can use any LLM API key, remember to set the base_url and api_key in the .env file) and set the paths:
  63. ```
  64. LLM_MODEL_NAME=your_llm_model_name_here
  65. LLM_BASE_URL=your_llm_base_url_here
  66. LLM_API_KEY=your_llm_api_key_here
  67. OLLAMA_MODEL_NAME=your_ollama_model_name_here
  68. OLLAMA_BASE_URL=your_ollama_base_url_here
  69. MARKDOWN_FOLDER_PATH=/path/to/your/markdown/folder
  70. RESULT_FOLDER_PATH=/path/to/your/result/folder
  71. ```
  72. ## Important Configuration Notes ⚠️
  73. Before running the application, you need to modify the following:
  74. 1. **MCP Server Configuration**:
  75. Edit `mcp_servers/servers_config.json` to match your local setup:
  76. ```json
  77. {
  78. "mcpServers": {
  79. "markdown_processor": {
  80. "command": "/path/to/your/uv",
  81. "args": [
  82. "--directory",
  83. "/path/to/your/project/mcp_servers",
  84. "run",
  85. "markdown_processor.py"
  86. ]
  87. }
  88. }
  89. }
  90. ```
  91. Replace `/path/to/your/uv` with the actual path to your uv executable. **You can use `which uv` to get the path**.
  92. Replace `/path/to/your/project/mcp_servers` with the absolute path to the mcp_servers directory in your project. (For **Windows** users, you can take a look at the example in the [Troubleshooting](#troubleshooting) section)
  93. 2. **Environment Variables**:
  94. Make sure to set proper paths in your `.env` file:
  95. ```
  96. MARKDOWN_FOLDER_PATH="/path/to/your/markdown/folder"
  97. RESULT_FOLDER_PATH="/path/to/your/result/folder"
  98. ```
  99. The application will validate these paths and throw an error if they contain placeholder values.
  100. You can run the following command to check your configuration:
  101. ```bash
  102. bash scripts/check.sh
  103. ```
  104. ## Usage
  105. ### Unit Test
  106. You can run the following command to run the unit test:
  107. ```bash
  108. bash scripts/unittest.sh
  109. ```
  110. ### Examples
  111. #### Single Prompt Examples
  112. The project includes two single prompt examples:
  113. 1. **Regular Mode**: Process a single prompt and display the complete response
  114. ```bash
  115. python example/single_prompt/single_prompt.py
  116. ```
  117. 2. **Streaming Mode**: Process a single prompt with real-time streaming output
  118. ```bash
  119. python example/single_prompt/single_prompt_stream.py
  120. ```
  121. Both examples accept an optional `--llm` parameter to specify which LLM provider to use:
  122. ```bash
  123. python example/single_prompt/single_prompt.py --llm=ollama
  124. ```
  125. > [!NOTE]
  126. > For more details, see the [Single Prompt Example README](example/single_prompt/README.md).
  127. #### Terminal Chatbot Examples
  128. The project includes two interactive terminal chatbot examples:
  129. 1. **Regular Mode**: Interactive terminal chat with complete responses
  130. ```bash
  131. python example/chatbot_terminal/chatbot_terminal.py
  132. ```
  133. 2. **Streaming Mode**: Interactive terminal chat with streaming responses
  134. ```bash
  135. python example/chatbot_terminal/chatbot_terminal_stream.py
  136. ```
  137. Both examples accept an optional `--llm` parameter to specify which LLM provider to use:
  138. ```bash
  139. python example/chatbot_terminal/chatbot_terminal.py --llm=ollama
  140. ```
  141. > [!NOTE]
  142. > For more details, see the [Terminal Chatbot Example README](example/chatbot_terminal/README.md).
  143. #### Streamlit Web Chatbot Example
  144. The project includes an interactive web-based chatbot example using Streamlit:
  145. ```bash
  146. streamlit run example/chatbot_streamlit/app.py
  147. ```
  148. This example features:
  149. - Interactive chat interface.
  150. - Real-time streaming responses.
  151. - Detailed MCP tool workflow visualization.
  152. - Configurable LLM settings (OpenAI/Ollama) and MCP tool display via the sidebar.
  153. ![MCP Chatbot Streamlit Demo](assets/chatbot_streamlit_demo_light.png)
  154. > [!NOTE]
  155. > For more details, see the [Streamlit Chatbot Example README](example/chatbot_streamlit/README.md).
  156. </details>
  157. ## Project Structure
  158. - `mcp_chatbot/`: Core library code
  159. - `chat/`: Chat session management
  160. - `config/`: Configuration handling
  161. - `llm/`: LLM client implementation
  162. - `mcp/`: MCP client and tool integration
  163. - `utils/`: Utility functions (e.g. `WorkflowTrace` and `StreamPrinter`)
  164. - `mcp_servers/`: Custom MCP servers implementation
  165. - `markdown_processor.py`: Server for processing Markdown files
  166. - `servers_config.json`: Configuration for MCP servers
  167. - `data-example/`: Example Markdown files for testing
  168. - `example/`: Example scripts for different use cases
  169. - `single_prompt/`: Single prompt processing examples (regular and streaming)
  170. - `chatbot_terminal/`: Interactive terminal chatbot examples (regular and streaming)
  171. - `chatbot_streamlit/`: Interactive web chatbot example using Streamlit
  172. ## Extending the Project
  173. You can extend this project by:
  174. 1. Adding new MCP servers in the `mcp_servers/` directory
  175. 2. Updating the `servers_config.json` to include your new servers
  176. 3. Implementing new functionalities in the existing servers
  177. 4. Creating new examples based on the provided templates
  178. ## Troubleshooting
  179. For Windows users, you can take the following `servers_config.json` as an example:
  180. ```json
  181. {
  182. "mcpServers": {
  183. "markdown_processor": {
  184. "command": "C:\\Users\\13430\\.local\\bin\\uv.exe",
  185. "args": [
  186. "--directory",
  187. "C:\\Users\\13430\\mcp_chatbot\\mcp_servers",
  188. "run",
  189. "markdown_processor.py"
  190. ]
  191. }
  192. }
  193. }
  194. ```
  195. - **Path Issues**: Ensure all paths in the configuration files are absolute paths appropriate for your system
  196. - **MCP Server Errors**: Make sure the tools are properly installed and configured
  197. - **API Key Errors**: Verify your API key is correctly set in the `.env` file

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.