📌Overview

Purpose: To provide an open-source client for testing and evaluating MCP servers and agents through an interactive chat interface.

Overview: The MCP Chat framework allows users to interact with multiple MCP servers, both in CLI and web modes, facilitating the evaluation and testing of various agents. It simplifies the process of interacting with language models through configurable settings and chat history management.

Key Features:

Interactive Command-Line Interface: Users can chat with models, run commands, and specify configurations directly from the CLI, enhancing flexibility for developers and testers.
Web Mode: Provides a user-friendly web interface for initiating chats and managing settings without command line complexities, with automatic saving of chat sessions.
Server Compatibility: Connects seamlessly to any MCP server across different environments (JS, Python, Docker), catering to diverse development setups.
Model Management: Allows selection of different language models and customization of system prompts to tailor interactions for specific use cases.
Chat History and Debugging: Captures and stores chat history and command usage, facilitating easy retrieval and debugging for improved workflow efficiency.

mcp-chat

Open Source Generic MCP Client for testing & evaluating MCP servers and agents

Quickstart

Make sure that you have ANTHROPIC_API_KEY exported in your environment or in a .env file in the root of the project. You can get an API key by signing up at the Anthropic Console keys page.

Simple use case that spawns an interactive chat prompt with the filesystem MCP server from CLI:

npx mcp-chat --server "npx -y @modelcontextprotocol/server-filesystem /Users/$USER/Desktop"

This will open up a chat prompt that you can use to interact with the servers and chat with an LLM.

Config

You can also specify your claude_desktop_config.json:

Mac:

npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows:

npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"

Web mode

You can run mcp-chat in web mode by specifying the --web flag (ensure ANTHROPIC_API_KEY is exported):

npx mcp-chat --web

In web mode, you can start new chats, send messages to the model, and dynamically configure MCP servers via the UI without command line options. Chats created via the Web UI are saved to ~/.mcpchats/chats just like CLI chats.

Features

Run via CLI in interactive mode or pass prompts directly with -p
Web mode chat interface with --web
Connect to any MCP server (JS, Python, Docker)
Choose models with -m
Customize system prompt with --system
Saves chat history with settings in ~/.mcpchat/chats including web chats
Save and restore command history in ~/.mcpchat/history
View tool call output and arguments within chat for debugging MCP servers

CLI Usage

Run prompts via CLI with the -p flag:

npx mcp-chat --server "npx mcp-server-kubernetes" -p "List the pods in the default namespace"

Choose a model with the -m flag:

npx mcp-chat --server "npx mcp-server-kubernetes" -m "claude-3.5"

Specify a custom system prompt with the --system flag:

npx mcp-chat --system "Explain the output to the user in pirate speak." --server "npx mcp-server-kubernetes" -p "List the pods in the default namespace"

For Developers of MCP Servers

Test a local build of a Node.js or Python MCP server:

Node.js:

# Directly executing built script
npx mcp-chat --server "/path/to/mcp-server-kubernetes/dist/index.js"
# Using node / bun
npx mcp-chat --server "node /path/to/mcp-server-kubernetes/dist/index.js"

Python:

# Using uv
npx mcp-chat --server "uv --directory /path/to/mcp-server-weather/ run weather.py"
# Using python / python3 - ensure dependencies installed or venv activated
npx mcp-chat --server "/path/to/mcp-server-weather/weather.py"

Development

Install dependencies and run the CLI:

git clone https://github.com/Flux159/mcp-chat
bun install
bun run dev

Develop mcp-chat while connecting to an MCP server:

npm run build && node dist/index.js --server "npx mcp-server-kubernetes" -p "List the pods in the default namespace"

Testing:

bun run test

Building:

bun run build

Publishing:

bun run publish

Publishing Docker:

bun run dockerbuild

Project Structure

├── src/
│   ├── index.ts            # Main client implementation & CLI params
│   ├── constants.ts        # Default constants
│   ├── interactive.ts      # Interactive chat prompt handling & logic
├── test/                   # Test files
│   ├── cli.test.ts         # Test CLI params
│   ├── config.test.ts      # Test config file parsing

Publishing New Release

Go to the releases page, click "Draft New Release," choose a tag with semantic versioning "v{major}.{minor}.{patch}", set a release title and description/changelog, then publish the release.

This triggers a build workflow that publishes the new version to npm. Version numbers in package.json are updated automatically by the workflow.

License

MIT License