A terminal-based interactive chat client for communicating with Model Context Protocol (MCP) servers using Anthropic's Claude models.

Designed for developers building and testing tools via the MCP spec.

• 🧑‍💻 Terminal chat interface with Claude
• 🔍 Auto-discovers tools from an MCP server
• 🧰 Executes Claude's tool_use calls live
• ✅ Validates tool inputs via JSON Schema
• 🪵 Full structured logging and debugging
• 🔁 Multi-turn conversation loop with memory
• 📎 File Attachments for Images and PDF

• Python 3.11+
• MCP tool server (conforming to the spec)
• .env file with Anthropic API key

Install with uv (recommended) or pip:

uv pip install -r requirements.txt
# or
pip install -r requirements.txt

Dependencies:

• anthropic
• anyio
• mcp
• python-dotenv
• jsonschema

{
  "provider": "anthropic",
  "model": "claude-3-haiku-20240307"
}

{
  "mcpServers": {
    "default": {
      "command": "python",
      "args": ["-m", "your_mcp_tool_server"],
      "env": {
        "MY_ENV_VAR": "value"
      }
    }
  }
}

ANTHROPIC_API_KEY=your-api-key-here

Run with default config:

python main.py

Custom configs:

python main.py --llm_config custom_llm_config.json --mcp_config custom_mcp_servers.json

1. You send a prompt in terminal
2. Claude replies with text or tool_use blocks
3. MCP client validates and calls the appropriate tool
4. Tool results are returned to Claude
5. Claude completes the response

All without leaving your terminal.

You can attach PDF and image files (.png, .jpg, .webp) to your prompt using the --file flag.

These files will be sent to Claude along with your message using base64 encoding and the correct MIME type.

• application/pdf
• image/png
• image/jpeg
• image/webp

python main.py --file ./sample.pdf

• Tools are discovered via tools/list
• Input schemas are parsed and validated
• Tool outputs must return a string (per Claude API)
• Errors are passed back as strings with content

• Make sure ANTHROPIC_API_KEY is in .env
• Set log level to DEBUG for full trace
• If Claude throws 400 errors:
  • Ensure tool_result.content is a string
  • Validate tool inputs match declared schema

• Support OpenAI, VertexAI
• Vendor-agnostic LLM integration
• SSE support
• Packaging
• Add tests and CLI improvements