Build a Python MCP Client to Test Servers From Your Terminal

Build the MCP Client’s CLI With argparse

Get back to your code editor and create a new file called cli.py inside the mcp_client package. Then, add the following content to the file:

import argparse
import pathlib

def parse_args():
    """Parse command line arguments and return parsed args."""
    parser = argparse.ArgumentParser(description="A minimal MCP client")
    parser.add_argument(
        "server_path",
        type=pathlib.Path,
        help="path to the MCP server script",
    )
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument(
        "--members",
        action="store_true",
        help="list the MCP server's tools, prompts, and resources",
    )
    return parser.parse_args()

In this file, you create a command-line argument parser using the ArgumentParser class. Then, you add an argument to specify the path to the MCP server’s script. You set the argument’s type to pathlib.Path so that the CLI converts the user-provided path string into a Path object, enhancing the app’s path management. The help argument allows you to provide descriptive help messages for the client users.

You also create a group of mutually exclusive command-line options. You need this because you don’t want the --members option to run with the --chat option that you’ll implement later. Next, you add the --members option as a stored Boolean value with an appropriate help message. That’s it! The CLI is ready for now.

mcp-client/
├── .git/
├── .venv/
├── mcp_client/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   └── mcp_client.py
├── mcp_server/
│   └── mcp_server.py
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── uv.lock

In the next section, you’ll write the code that’ll make the --members option list the MCP server’s tools, prompts, and resources.

Add the --members Command-Line Option

The --members command-line option will provide a complete list of the target MCP server’s members or primitives. You’ll start with the list_all_members() function, which will be part of the public interface of MCPClient:

class MCPClient:
    # ...

    async def list_all_members(self) -> None:
        """List all available tools, prompts, and resources."""
        print("MCP Server Members")
        print("=" * 50)

        sections = {
            "tools": self.client_session.list_tools,
            "prompts": self.client_session.list_prompts,
            "resources": self.client_session.list_resources,
        }
        for section, listing_method in sections.items():
            await self._list_section(section, listing_method)

        print("\n" + "=" * 50)

In this function, you print a heading for the list of members. Then, you create a dictionary that maps the sections to the corresponding listing method in the client session. Next, you loop over the dictionary items to call ._list_section() with the corresponding section name and method. This retrieves the data from the MCP server.

Here’s the implementation of your ._list_section() helper method. Because it’s a non-public method, it isn’t part of the class’s public interface:

class MCPClient:
    # ...

    async def _list_section(
        self,
        section: str,
        list_method: Callable[[], Awaitable[Any]],
    ) -> None:
        try:
            items = getattr(await list_method(), section)
            if items:
                print(f"\n{section.upper()} ({len(items)}):")
                print("-" * 30)
                for item in items:
                    description = item.description or "No description"
                    print(f" > {item.name} - {description}")
            else:
                print(f"\n{section.upper()}: None available")
        except Exception as e:
            print(f"\n{section.upper()}: Error - {e}")

In the ._list_section() method, you take a section name, such as "tools", "prompts", or "resources", and a ClientSession.list_* method object as arguments. Then, you dynamically call the method using getattr() and retrieve the members or items in the section. Finally, you print the section title, the number of items, and the details for each one, including its name and description.

If no items are found, you print a message indicating that the section is empty. The method also includes error handling to catch and display any exceptions that occur during the process, ensuring that failures don’t crash the program but instead produce a clear error message for the user.

Update the Client’s Entry-Point Script

To make everything work, you need to fully update your __main__.py file with the following changes:

import asyncio

from mcp_client.cli import parse_args
from mcp_client.mcp_client import MCPClient

async def main() -> None:
    """Run the MCP client with the specified options."""
    args = parse_args()
    if not args.server_path.exists():
        print(f"Error: Server script '{args.server_path}' not found")
        return

    try:
        async with MCPClient(str(args.server_path)) as client:
            if args.members:
                await client.list_all_members()
    except RuntimeError as e:
        print(e)

if __name__ == "__main__":
    asyncio.run(main())

In this update to the main() function, you grab the command-line arguments by calling parse_args() from the cli.py module. The conditional checks whether the path to the MCP server script exists. If not, then you print an error message and return, which eventually causes the application to terminate.

Next, you have a try block where you create an MCPClient instance in an async with statement. The conditional inside the with code block checks whether the user provided the --members option at the command line. If that’s the case, then you await the call to .list_all_members(). If an error occurs, you print the error message to the screen.

To try out your MCP client, make sure you’re in the project’s root folder and then run the following command:

$ uv run python -m mcp_client mcp_server/mcp_server.py --members
MCP Server Members
==================================================

TOOLS (1):
------------------------------
 > echo - Echo back the message.

PROMPTS (1):
------------------------------
 > greeting_prompt - A simple greeting prompt.

RESOURCES (1):
------------------------------
 > greeting_file - The greeting text file.

==================================================

The output looks great! It lists the three sections along with their respective items. This allows you to assess the target server’s capabilities and gain a better understanding of how to use it effectively.

Add the --chat Command-Line Option

Go back to the cli.py file and add the following code to it:

import argparse
import pathlib

def parse_args():
    """Parse command line arguments and return parsed args."""
    parser = argparse.ArgumentParser(description="A minimal MCP client")
    parser.add_argument(
        "server_path",
        type=pathlib.Path,
        help="path to the MCP server script",
    )
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument(
        "--members",
        action="store_true",
        help="list the MCP server's tools, prompts, and resources",
    )
    group.add_argument(
        "--chat",
        action="store_true",
        help="start an AI-powered chat with MCP server integration",
    )
    return parser.parse_args()

The --chat option will trigger a minimal chat interface on the command line. Next, you’ll set up the chat interface where you’ll be able to enter your queries and receive the AI-powered backend’s response.

To write the chat interface, go ahead and create a new file called chat.py under the mcp_client package. Then, add the following code to it:

async def run_chat(handler) -> None:
    """Run an AI-handled chat session."""
    print("\nMCP Client's Chat Started!")
    print("Type your queries or 'quit' to exit.")

    while True:
        try:
            if not (query := input("\nYou: ").strip()):
                continue
            if query.lower() == "quit":
                break

            print("\n" + await handler.process_query(query))
        except Exception as e:
            print(f"\nError: {str(e)}")

    print("\nGoodbye!")

This is quite a short function. It takes an AI-powered handler as an argument, prints an informative message, and starts the chat loop.

The while loop is an intentional infinite loop that terminates only when the user enters quit at the command line.

In the loop, you grab the user query using the built-in input() function, which you store in the query variable. Next, you use this query as an argument to handler.process_query(), which will pass the query to an OpenAI model for further processing. If an error occurs, then you print the corresponding error message.

Create a Chat Handler With OpenAI’s Python SDK

Interacting with an MCP server requires an AI-powered client. Up to this point, your MCP client doesn’t have AI-powered capabilities. In this section, you’ll implement that. You’ll use OpenAI’s Python SDK, which you already installed in your working environment.

Go back to your code editor and create a new file called handlers.py under the mcp_client package. Then, start with the following code:

import json
import os

from mcp import ClientSession
from openai import OpenAI

MODEL = "gpt-4o-mini"
MAX_TOKENS = 1000

class OpenAIQueryHandler:
    """Handle OpenAI API interaction and MCP tool execution."""

    def __init__(self, client_session: ClientSession):
        self.client_session = client_session
        if not (api_key := os.getenv("OPENAI_API_KEY")):
            raise RuntimeError(
                "Error: OPENAI_API_KEY environment variable not set",
            )
        self.openai = OpenAI(api_key=api_key)

After the required imports, you define two constants, MODEL and MAX_TOKENS, which hold the model you’ll use and the maximum number of allowed tokens, as their names suggest.

Next, you define the OpenAIQueryHandler class. The initializer takes a ClientSession as an argument and defines the .client_session and .openai attributes. It also verifies whether an OpenAI API key is set up in your environment.

The heart of the handler is the .process_query() method, which accepts a user query as a string and performs the following actions:

• Forwarding the query to OpenAI along with the list of available tools on the MCP server
• Inspecting the model’s response to determine whether tool calls are needed
• Triggering any required tool calls
• Requesting a final answer from the model that integrates any tool outputs

Here’s the implementation of your process_query() method:

class OpenAIQueryHandler:
    # ...

    async def process_query(self, query: str) -> str:
        """Process a query using OpenAI and available MCP tools."""
        # Get initial model's response and decision on tool calls
        messages = [{"role": "user", "content": query}]
        initial_response = self.openai.chat.completions.create(
            model=MODEL,
            max_tokens=MAX_TOKENS,
            messages=messages,
            tools=await self._get_tools(),
        )

        current_message = initial_response.choices[0].message
        result_parts = []

        if current_message.content:
            result_parts.append(current_message.content)

        # Handle tool usage if present
        if tool_calls := current_message.tool_calls:
            messages.append(
                {
                    "role": "assistant",
                    "content": current_message.content or "",
                    "tool_calls": tool_calls,
                }
            )

            # Execute tools
            for tool_call in tool_calls:
                tool_result = await self._execute_tool(tool_call)
                result_parts.append(tool_result["log"])
                messages.append(tool_result["message"])

            # Get final model's response after tool execution
            final_response = self.openai.chat.completions.create(
                model=MODEL,
                max_tokens=MAX_TOKENS,
                messages=messages,
            )

            if content := final_response.choices[0].message.content:
                result_parts.append(content)

        return "Assistant: " + "\n".join(result_parts)

First, you construct an initial conversation with the OpenAI model using the user’s query. You invoke .create(), passing in the model, token limits, messages, and the result of calling ._get_tools(), which packages the MCP tools into a schema that OpenAI can process.

The model returns a message object that may include direct content and optionally instructions to call one or more tools on the MCP server.

If the model produces content, then you append it to a list of result parts. Then, you check whether the response requires any tool calls. If so, you append the assistant message with the tool-call metadata to the conversation. Next, you loop through the tools and delegate execution to ._execute_tool().

After executing all tool calls, you make a second call to the model to request a final answer that incorporates the tool outputs. To wrap up the process, you append the final content and return a formatted answer that combines all parts. This will be the AI assistant’s response in the chat interface.

The ._get_tools() helper is fairly straightforward. Here’s its code:

class OpenAIQueryHandler:
    # ...

    async def _get_tools(self) -> list:
        """Get MCP tools formatted for OpenAI."""
        response = await self.client_session.list_tools()
        return [
            {
                "type": "function",
                "function": {
                    "name": tool.name,
                    "description": tool.description or "No description",
                    "parameters": getattr(
                        tool,
                        "inputSchema",
                        {"type": "object", "properties": {}},
                    ),
                },
            }
            for tool in response.tools
        ]

In this method, you get the MCP server’s tools by calling .list_tools(). Then, you transform each tool into an OpenAI-ready JSON schema format that describes the function to call. Each tool contains a name, description, and input schema.

This information is crucial because it enables OpenAI models to determine whether to invoke any tools to generate the final response that integrates the resulting data.

Finally, you need the ._execute_tool() helper method. Here’s its implementation:

class OpenAIQueryHandler:
    # ...

    async def _execute_tool(self, tool_call) -> dict:
        """Execute an MCP tool call and return formatted result."""
        tool_name = tool_call.function.name
        tool_args = json.loads(tool_call.function.arguments or "{}")

        try:
            result = await self.client_session.call_tool(
                tool_name, tool_args,
            )
            content = result.content[0].text if result.content else ""
            log = f"[Used {tool_name}({tool_args})]"
        except Exception as e:
            content = f"Error: {e}"
            log = f"[{content}]"

        return {
            "log": log,
            "message": {
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": content,
            },
        }

In the ._execute_tool() helper, you take a tool_call object from the model’s output and run it through your ClientSession. To do this, you first extract the tool’s name and parse its arguments using the json.loads() function.

Next, you await client_session.call_tool() to execute the current tool on the MCP server side. If the tool returns structured content, then you extract the text of its first item. Otherwise, you set the content to an empty string. You also construct a log string summarizing the invocation to provide user feedback in the chat interface.

If the tool execution fails due to an exception, then you catch the error and create a log accordingly. Finally, you return a dictionary with two keys: "log" containing the summary string, and "message" containing the tool role message for the AI model.

That’s it! You’ve coded the AI-powered handler for your client’s chat interface. It’s time to update the MCPClient class.

Connect the Chat With the MCP Client

Go back to the mcp_client.py file. First, update the imports to add the chat function and the OpenAIQueryHandler class:

import sys
from contextlib import AsyncExitStack
from typing import Any, Awaitable, Callable, ClassVar, Self

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from mcp_client import chat
from mcp_client.handlers import OpenAIQueryHandler

# ...

Once you’ve updated the imports, you can add the .run_chat() method to MCPClient:

# ...

class MCPClient:
    # ...

    async def run_chat(self) -> None:
        """Start interactive chat with MCP server using OpenAI."""
        try:
            handler = OpenAIQueryHandler(self.client_session)
            await chat.run_chat(handler)
        except RuntimeError as e:
            print(e)

In the .run_chat() method, you create the AI handler for the chat session and then call the .run_chat() function to start the chat interface. If an error occurs, then you print an appropriate error message to inform the user.

With these updates in place, you can now update the app’s entry-point script so that you can use the new chat functionality from the command line.

Update the Client’s Entry-Point Script

To integrate the --chat option into your client’s behavior, you just need to make a minimal change to the __main__.py file. Consider the highlighted lines below:

import asyncio

from mcp_client.cli import parse_args
from mcp_client.mcp_client import MCPClient

async def main() -> None:
    """Run the MCP client with the specified options."""
    args = parse_args()
    if not args.server_path.exists():
        print(f"Error: Server script '{args.server_path}' not found")
        return

    try:
        async with MCPClient(str(args.server_path)) as client:
            if args.members:
                await client.list_all_members()
            elif args.chat:
                await client.run_chat()
    except RuntimeError as e:
        print(e)

if __name__ == "__main__":
    asyncio.run(main())

In this update, you just add an elif branch to the conditional. This branch checks whether the user provided the --chat command-line option. If that’s the case, then you call .run_chat() on the client object.

Now you’re all set up to give the chat interface a try. Go ahead, run the following command, and then enter a request for the assistant:

$ uv run python -m mcp_client mcp_server/mcp_server.py --chat

MCP Client's Chat Started!
Type your queries or 'quit' to exit.

You: echo My first MCP client!

Assistant: [Used echo({'message': 'My first MCP client!'})]
My first MCP client!

You:

That looks great! The chat interface works and lets you query the model and receive a response. Notice how the model incorporates the tool-call result into its reply. This confirms that the target MCP server was used correctly. To exit the chat interface, type quit and press Enter.

Make the MCP Client App Installable

In this final section, you’ll edit the pyproject.toml file so you can use uv to build and install your MCP client locally with an editable install.

At this point, your project should have the following directory structure:

mcp-client/
├── .git/                    # Git version control
├── .venv/                   # Python virtual environment
├── mcp_client/              # MCP client
│   ├── __init__.py
│   ├── __main__.py
│   ├── chat.py
│   ├── cli.py
│   ├── handlers.py
│   └── mcp_client.py
├── mcp_server/              # Test MCP server
│   └── mcp_server.py
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── uv.lock

Go ahead and open pyproject.toml in your code editor. Then, update it as shown below:

[project]
name = "mcp-client"
version = "0.1.0"
description = "MCP client for testing MCP servers."
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
    "mcp>=1.20.0",
    "openai>=2.6.1",
]

[project.scripts]
mcp-client = "mcp_client.__main__:cli_main"

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
include = ["mcp_client*"]  # Only include mcp_client package
exclude = ["mcp_server*"]  # Explicitly exclude mcp_server

First, you update the project description. Next, you set up the entry-point script in the [project.scripts] table. Note that you’ve set this key to mcp_client.__main__:cli_main, but this function isn’t defined in the __main__.py file yet. Add the function just below main(). Here’s the code:

# ...

def cli_main():
    """Entry point for the mcp-client CLI app."""
    asyncio.run(main())

# ...

You need this function because the setuptools build system can’t handle async functions like main(). It only supports synchronous callables. A possible solution is to wrap the async main() in a synchronous function, such as cli_main() in this example.

You’ll use setuptools as the build system, which is configured in the [build-system] table.

Because this project includes a test MCP server in a top-level folder, you must instruct the build system to exclude this folder from the build. That’s what you do in the [tool.setuptools.packages.find] table.

To try this setup out, go ahead and run the following in your terminal:

$ uv sync
Resolved 33 packages in 353ms
      Built mcp-client @ file:///Users/realpython/mcp-client
Prepared 1 package in 551ms
Installed 1 package in 1ms
 + mcp-client==0.1.0 (from file:///Users/realpython/mcp-client)

When you run this command, uv sets up everything for you using the updated pyproject.toml file. From now on, you can run your MCP client using the mcp-client command directly once you activate the project’s virtual environment:

$ source .venv/bin/activate
(mcp-client) $ mcp-client --help
usage: mcp-client [-h] (--members | --chat) server_path

A minimal MCP client

positional arguments:
  server_path           path to the MCP server script

options:
  -h, --help            show this help message and exit
  --members             list the MCP server's tools, prompts, and resources
  --chat                start an AI-powered chat with MCP server integration

As you can see, the mcp-client command now works when used directly in the project’s virtual environment.

That’s it! You’ve built a command-line interface MCP client using the Python SDK for MCP and OpenAI. You can use this client to test your MCP servers during development. However, keep in mind that this is a minimal client that doesn’t cover production concerns such as security, concurrency, error handling, tool permissions, and others.