Navigation
MCP-Chat: Empowering Server Testing & Agent Validation - MCP Implementation

MCP-Chat: Empowering Server Testing & Agent Validation

Versatile open-source MCP client empowering seamless testing & evaluation of servers/agents. Flexible, community-driven, and built for rigorous validation.

Developer Tools
4.5(88 reviews)
132 saves
61 comments

43% of users reported increased productivity after just one week

About MCP-Chat

What is MCP-Chat: Empowering Server Testing & Agent Validation?

MCP-Chat is an open-source tool designed to simplify the testing and validation of Model Context Protocol (MCP) servers and agents. It acts as a universal client, enabling developers to interact with MCP-compliant servers through both command-line (CLI) and web-based interfaces. The tool supportsAnthropic models and provides a streamlined environment to evaluate server performance, debug tool interactions, and customize model behavior.

How to Use MCP-Chat: Empowering Server Testing & Agent Validation?

Getting started with MCP-Chat requires minimal setup:

  1. Set up your environment: Export the ANTHROPIC_API_KEY or store it in a .env file.
  2. Run CLI commands: Use npx mcp-chat with flags like --server to specify servers (e.g., npx -y @modelcontextprotocol/server-filesystem for file system access).
  3. Access Web mode: Add the --web flag to launch a browser-based UI for chat management and server configuration.
  4. Customize interactions: Adjust models (-m), system prompts (--system), and save chat histories for reproducibility.

MCP-Chat Features

Key Features of MCP-Chat: Empowering Server Testing & Agent Validation?

MCP-Chat offers a robust set of features tailored for developers:

  • Cross-platform compatibility: Supports Node.js, Python, and Docker-based servers.
  • Dynamic configuration: Switch models (e.g., claude-3.5), define custom system prompts, and override server settings.
  • Debugging insights: View tool call arguments and outputs directly in chat logs to troubleshoot server behavior.
  • Chat persistence: Automatically saves chat histories and command logs to ~/.mcpchat.
  • Web interface: Manage multiple chats, export sessions, and configure servers without CLI commands.

Use Cases of MCP-Chat: Empowering Server Testing & Agent Validation?

Common scenarios include:

  • Server validation: Test new MCP server implementations against real-world prompts (e.g., querying Kubernetes pod statuses).
  • Agent debugging: Isolate tool call failures by reviewing argument logs and model responses.
  • Rapid prototyping: Iterate on server logic during development by pointing MCP-Chat to local builds (e.g., Python scripts).
  • Collaborative workflows: Share web-based chat sessions with team members for consistent testing.

MCP-Chat FAQ

FAQ from MCP-Chat: Empowering Server Testing & Agent Validation?

Q: How do I connect a custom MCP server?
Specify the server path via --server. For local builds, use direct file paths (e.g., node /path/to/your-server.js).

Q: Does Web mode require API keys?
Yes, ANTHROPIC_API_KEY must be set in the environment for Web mode to function.

Q: Can I use non-Anthropic models?
Currently, only Anthropic models are supported. Support for additional providers may be added in future releases.

Q: Where are chat histories stored?
All chats (CLI and Web) are saved to ~/.mcpchat/chats with metadata for easy reference.

Content

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 just specify your claude_desktop_config.json (Mac):

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

Or (Windows):

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

Web mode

https://github.com/user-attachments/assets/b7e8a648-8084-4955-8cdf-fc6eb141572e

You can also run mcp-chat in web mode by specifying the --web flag (make sure to have ANTHROPIC_API_KEY exported in your environment):

npx mcp-chat --web

In web mode, you can start new chats, send messages to the model, and dynamically configure the mcp servers via the UI - no need to specify on the command line. In addition, chats created via the Web UI are saved to ~/.mcpchats/chats just like chats created via the CLI.

Features

  • Run via CLI in interactive mode or directly pass prompts with -p
  • Web mode to chat with models via a web interface --web
  • Connect to any MCP server (JS, Python, Docker) in production or during development
  • Choose between models with -m
  • Customize system prompt with --system
  • Saves chat history with settings in ~/.mcpchat/chats including web chats
  • Save and restore commands in ~/.mcpchat/history
  • View tool call output and arguments directly in chat to help debug 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"

This runs the prompt with the kubenertes mcp-server & exits after the response is received on stdout.

Choose a model to chat with via CLI with the -m flag:

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

Uses the model claude-3.5 to chat with. Note that currently only Anthropic models are supported.

Custom system prompt:

--system flag can be used to specify a system prompt:

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

You can pass in a local build of a python or node mcp-server to test it out with mcp-chat:

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:

# Python: Using uv
npx mcp-chat --server "uv --directory /path/to/mcp-server-weather/ run weather.py"
# Using python / python3 - make sure to run in venv or install deps globally
npx mcp-chat --server "/path/to/mcp-server-weather/weather.py"

Development

Install dependencies & run the CLI:

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

To develop mcp-chat while connecting to an mcp-server, make a build & run the CLI with the server flag:

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 on "Draft New Release", click "Choose a tag" and create a new tag by typing out a new version number using "v{major}.{minor}.{patch}" semver format. Then, write a release title "Release v{major}.{minor}.{patch}" and description / changelog if necessary and click "Publish Release".

This will create a new tag which will trigger a new release build via the cd.yml workflow. Once successful, the new release will be published to npm. Note that there is no need to update the package.json version manually, as the workflow will automatically update the version number in the package.json file & push a commit to main.

License

MIT License

Related MCP Servers & Clients