MCP Chat Client

A simple command-line chat interface that enables LLMs to take actions via Model Context Protocol (MCP) servers, with support for models from OpenAI, Anthropic, and Google.

Features

• Connect to multiple MCP servers simultaneously
• Support for multiple LLM providers (Anthropic, OpenAI, Google)
• Display LLM's thinking process with -t flag
• Maintain conversation memory across queries
• Support for both direct server scripts and config files

Prerequisites

• Python 3.8+
• Node.js and npx (required for many MCP servers)

Installation

1. Ensure Node.js and npm are installed:

   node --version
   npm --version
   

   If not installed, download from nodejs.org

2. Clone this repository:

   git clone https://github.com/wendy-aw/mcp_chat_client.git
   cd mcp_chat_client
   

3. Install dependencies:

   pip install .
   # or using uv (recommended)
   uv pip install .
   

4. Create a .env file with your API keys. You only need the keys for the models you plan to use.

   ANTHROPIC_API_KEY=your_api_key_here
   OPENAI_API_KEY=your_openai_key_here
   GEMINI_API_KEY=your_gemini_key_here
   

5. Create a config.json file with your server configurations.

Example config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/directory"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    },
    "name_of_remote_server": {
      "command": "sse", 
      "args": ["http://url_to_server/sse"]
    }
  }
}

Server Configuration

1. Remote Servers (SSE):

   • Use "command": "sse"
   • Use "args": ["url_to_server/sse"] for remote servers
   • Make sure the port matches your server's configuration and /sse is the endpoint.

2. Local Servers within this application (stdio):

   • Specify the command to run the server (e.g., "npx", "python")
   • Provide arguments in an array (e.g., ["-y", "package-name"])
   • Optionally provide environment variables with "env": {}

Usage

Connect to a server using a config file:

python client.py config.json

Connect directly to a server script:

python client.py /path/to/server_script.js

Show thinking process:

python client.py config.json -t

Commands

During a chat session:

• /quit - Exit the client
• /clear - Clear conversation memory
• /tools - Show available tools
• /prompts - Show available prompts
• /<prompt_name> - Use a specific prompt template

Using Prompt Templates

Prompt templates that are defined in the MCP servers can be invoked in queries using the /command syntax:

# This will apply the "gen_report" prompt template to "sales by region"
Query: /gen_report sales by region

If no further text is provided after the command, the prompt template will be applied to the output of the previous message in the message history.

Available MCP Servers

Refer to the official MCP documentation for a list of available MCP servers. You can also create custom servers in the custom_servers/ folder. See the custom server openai_web_search.py.

Troubleshooting Server Connection Errors

If you encounter the "unhandled errors in a TaskGroup" error:

1. Check Server Status: Make sure your server is running on the specified port
2. Verify Configuration: Ensure port numbers match in both server and config
3. Host Binding: Server must use host="0.0.0.0" (not 127.0.0.1)
4. Right endpoint: If using SSE, make sure the endpoint is /sse and not the root endpoint.

If using stdio servers, check for syntax errors in your command or arguments.