What is mcp-client-ref?

mcp-client-ref is a terminal-based Model Context Protocol (MCP) client built with the Textual TUI library. It lets you connect to MCP servers and interact with them via a language model (defaults to Claude Haiku).

How to use mcp-client-ref?

Install dependencies with uv sync, then run uv run scripts/client.py <mcp_servers_config_path>. The config file is a JSON file that lists your MCP servers in the format used by Claude Desktop. Set ANTHROPIC_API_KEY in a .env file for the default model. You can change the model by editing the client code.

Key features of mcp-client-ref

- Terminal-based TUI interface using the Textual library
- Connects to MCP servers via a JSON config file
- Defaults to Claude Haiku (configurable via code)
- Includes an MCP server inspector for debugging

Use cases of mcp-client-ref

- Debug and test MCP servers with the built‑in inspector
- Interact with MCP servers through a terminal LLM client
- Run a lightweight MCP client without a full IDE

FAQ from mcp-client-ref

What model does mcp-client-ref use by default?

The client uses the Claude Haiku model by default, so you need an ANTHROPIC_API_KEY in your .env file.

Can I use a different model?

Yes, the client uses the magentic library for LLM connections, and you can configure a different model in the client code.

How do I specify which MCP servers to connect to?

Pass the path to a JSON config file as a command‑line argument. The file follows the format used by the Claude Desktop app.

Is there a way to debug MCP servers?

Yes, you can open the MCP server inspector screen from the command palette inside the application.