Create a Python Model Context Protocol client to test servers from the terminal.
This tutorial shows how to build a minimal Python Model Context Protocol client for testing servers from the terminal. Using uv, argparse, asyncio, the MCP Python SDK, and OpenAI, it connects over stdio, lists tools, prompts, and resources, and sends server responses into an AI-powered chat. The guide covers project setup, dependencies, and practical questions the client helps answer while developing Model Context Protocol servers.
Key Points Summary
- The article shows how to build a minimal Python MCP client for testing Model Context Protocol servers from the terminal.
- It uses the MCP Python SDK, `asyncio`, `argparse`, and the OpenAI Python SDK to connect to a server and power an AI chat.
- The client can list a server’s tools, prompts, and resources through a `ClientSession` before running chat-based tests.
- The project is aimed at developers who need a quick way to validate MCP server behavior without building a full UI.
Meta description: Build a Python Model Context Protocol client to test servers from your terminal using uv, argparse, ClientSession, stdio, and OpenAI Python SDK.
Tags: Python, Model Context Protocol, OpenAI, Command line, uv
Featured image: Abstract friendly illustration showing a terminal window, a connected server node, and a chat bubble, with no people, no logos, and no words.
This article is for developers who need a Python Model Context Protocol client to test servers from your terminal. It explains how to connect to a Model Context Protocol server through the standard input/output transport, list tools, prompts, and resources, and use server tool responses inside an AI-powered chat. The project uses the MCP Python SDK, argparse, asyncio, and the OpenAI Python SDK.
Why build a minimal command-line client?
When you are coding Model Context Protocol servers, a full user interface is often unnecessary. A small command-line client can answer three practical questions: can the server start, can it speak the protocol over the standard input/output transport, and does it expose the capabilities you expect? In this project, the client lists tools, prompts, and resources, then feeds server tool responses into an AI-powered chat.
The tutorial also points to related material. It does not cover creating servers in detail; readers can learn more in the Python MCP Server: Connect LLMs to Your Data tutorial. For the agent side, Real Python offers Build an AI Agent From Scratch in Python live course, where you build the agent loop by hand and learn why agents do what they do. You can join the waitlist to hear about the next dates. The full article is available at https://realpython.com/python-mcp-client/. The source page also promotes a Python Tricks newsletter delivered to your inbox every couple of days.
Prerequisites before coding
The project assumes you can manage a Python project with uv. If you prefer not to use uv, you can use a combination of alternative tools such as pyenv, venv, pip, or poetry. You should also know the basics of working with the asyncio and argparse libraries from the standard library. The tutorial links resources for Managing Python Projects With uv: An All-in-One Solution, Python’s asyncio: A Hands-On Walkthrough, and Build Command-Line Interfaces With Python’s argparse.
Familiarity with OpenAI’s Python API, openai, is helpful because you will use this library to power the chat functionality of your client. The project also uses the MCP Python SDK. You do not need every prerequisite before starting; the tutorial says that is completely okay because you learn through the process of getting your hands dirty. If you get stuck, take some time to review the linked resources, then return to the code.
You will also need a Model Context Protocol server to try your client as you build it. If you do not have one available, the tutorial says you can use the server provided in step 2. You can download the project’s source code and related files from the tutorial’s download link. You can also take the interactive quiz titled Build a Python MCP Client to Test Servers From Your Terminal. The quiz gives a score upon completion to help you track your learning progress.
Step-by-step project setup
- Open a terminal window and move to a directory where you typically store your projects. If you are using uv, create the project scaffold by running `uv init mcp-client`.
- Enter the new project directory with `cd mcp-client/`. The first command creates a new Python project in an `mcp-client/` directory.
- Add the project dependencies by running `uv add "mcp>=2.2.0,<3.0" "openai>=3.16.2,<4.0"`. These commands install the MCP Python SDK and the OpenAI Python SDK within the version ranges shown.
- Inspect the generated directory structure. It contains `.git/`, `.gitignore`, `.python-version`, `README.md`, `main.py`, and `pyproject.toml`. The `.git/` directory and the `.gitignore` file help you version-control the project.
- Read the `.python-version` file. This file contains the default Python version for the current project. It tells uv which Python version to use when creating a dedicated virtual environment for the project. The file will contain the version number of the Python interpreter you are currently using.
- Use `README.md` to provide basic documentation for your project. The `main.py` file provides a Python script that you can optionally use as the project’s entry point. The tutorial does not use this file, so you can remove it.
- Plan the client around three tasks: connect to a server through the standard input/output transport, discover capabilities, and run a chat. Use argparse to create the command-line interface, and use the MCP Python SDK for the protocol connection.
- Call `.list_tools()`, `.list_prompts()`, and `.list_resources()` on a `ClientSession` instance to list the server’s capabilities. These calls let you confirm what the server exposes before trying the chat path.
- Use the OpenAI Python SDK to integrate MCP tool responses into an AI-powered chat session. The tutorial then moves through setup, client implementation, capability discovery, chat handling, and packaging so you can test servers from your terminal.
What the client helps you test
The value of this project is separation. You can first test whether a server responds over the standard input/output transport. You can then inspect tools, prompts, and resources without building a full application. Finally, you can connect those server capabilities to a chat session powered by OpenAI’s Python SDK.
This approach is useful for developers who are writing servers and need a quick way to validate behavior. It is not a complete server tutorial, and it is not a production chat application. It is a minimal Model Context Protocol client for the command line, built to make server testing easier.
Common mistakes
- Skipping the version ranges. The tutorial specifies `"mcp>=2.2.0,<3.0"` and `"openai>=3.16.2,<4.0"`; using different versions can create surprises.
- Treating `main.py` as required. The project does not use it as the entry point, and you can remove it.
- Forgetting the server dependency. You need a Model Context Protocol server to test the client. If you do not have one, use the server provided in step 2.
- Mixing project management tools without consistency. The article uses uv, but alternatives such as pyenv, venv, pip, or poetry require careful environment setup.
- Ignoring prerequisites. The project uses asyncio, argparse, and the OpenAI Python SDK. If those are unfamiliar, review the linked resources before continuing.

Comments (0)