mcpchatbot example

!mcp chatbot

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.

[!tip] for chinese version, please refer to readme_zh.md.

overview

chatbot streamlit example

workflow tracer example

• 🚩 update (2025-04-11):
  • added chatbot streamlit example.
• 🚩 update (2025-04-10):
  • more complex llm response parsing, supporting multiple mcp tool calls and multiple chat iterations.
  • added single prompt examples with both regular and streaming modes.
  • added interactive terminal chatbot examples.

this project includes:

• simple/complex cli chatbot interface
• integration with some builtin mcp server like (markdown processing tools)
• support for customized llm (e.g. qwen) and ollama
• example scripts for single prompt processing in both regular and streaming modes
• interactive terminal chatbot with regular and streaming response modes

requirements

• python 3.10+
• dependencies (automatically installed via requirements):
  • python-dotenv
  • mcp[cli]
  • openai
  • colorama

installation

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:

     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
     

important configuration notes ⚠️

before running the application, you need to modify the following:

1. mcp server configuration: edit mcp_servers/servers_config.json to match your local setup:

   {
       "mcpservers": {
           "markdown_processor": {
               "command": "/path/to/your/uv",
               "args": [
                   "--directory",
                   "/path/to/your/project/mcp_servers",
                   "run",
                   "markdown_processor.py"
               ]
           }
       }
   }
   

   replace /path/to/your/uv with the actual path to your uv executable. you can use which uv to get the path. 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 section)

2. environment variables: make sure to set proper paths in your .env file:

   markdown_folder_path="/path/to/your/markdown/folder"
   result_folder_path="/path/to/your/result/folder"
   

   the application will validate these paths and throw an error if they contain placeholder values.

you can run the following command to check your configuration:

bash scripts/check.sh

usage

unit test

you can run the following command to run the unit test:

bash scripts/unittest.sh

examples

single prompt examples

the project includes two single prompt examples:

1. regular mode: process a single prompt and display the complete response

   python example/single_prompt/single_prompt.py
   

2. streaming mode: process a single prompt with real-time streaming output

   python example/single_prompt/single_prompt_stream.py
   

both examples accept an optional --llm parameter to specify which llm provider to use:

python example/single_prompt/single_prompt.py --llm=ollama

[!note] for more details, see the single prompt example readme.

terminal chatbot examples

the project includes two interactive terminal chatbot examples:

1. regular mode: interactive terminal chat with complete responses

   python example/chatbot_terminal/chatbot_terminal.py
   

2. streaming mode: interactive terminal chat with streaming responses

   python example/chatbot_terminal/chatbot_terminal_stream.py
   

both examples accept an optional --llm parameter to specify which llm provider to use:

python example/chatbot_terminal/chatbot_terminal.py --llm=ollama

[!note] for more details, see the terminal chatbot example readme.

streamlit web chatbot example

the project includes an interactive web-based chatbot example using streamlit:

streamlit run example/chatbot_streamlit/app.py

this example features:

• interactive chat interface.
• real-time streaming responses.
• detailed mcp tool workflow visualization.
• configurable llm settings (openai/ollama) and mcp tool display via the sidebar.

!mcp chatbot streamlit demo

[!note] for more details, see the streamlit chatbot example readme.

project structure

• mcp_chatbot/: core library code
  • chat/: chat session management
  • config/: configuration handling
  • llm/: llm client implementation
  • mcp/: mcp client and tool integration
  • utils/: utility functions (e.g. workflowtrace and streamprinter)
• mcp_servers/: custom mcp servers implementation
  • markdown_processor.py: server for processing markdown files
  • servers_config.json: configuration for mcp servers
• data-example/: example markdown files for testing
• example/: example scripts for different use cases
  • single_prompt/: single prompt processing examples (regular and streaming)
  • chatbot_terminal/: interactive terminal chatbot examples (regular and streaming)
  • chatbot_streamlit/: interactive web chatbot example using streamlit

extending the project

you can extend this project by:

1. adding new mcp servers in the mcp_servers/ directory
2. updating the servers_config.json to include your new servers
3. implementing new functionalities in the existing servers
4. creating new examples based on the provided templates

troubleshooting

for windows users, you can take the following servers_config.json as an example:

{
    "mcpservers": {
        "markdown_processor": {
            "command": "c:\\users\\13430\\.local\\bin\\uv.exe",
            "args": [
                "--directory",
                "c:\\users\\13430\\mcp_chatbot\\mcp_servers",
                "run",
                "markdown_processor.py"
            ]
        }
    }
}

• path issues: ensure all paths in the configuration files are absolute paths appropriate for your system
• mcp server errors: make sure the tools are properly installed and configured
• api key errors: verify your api key is correctly set in the .env file