MCP CLI Chat

A command-line chat application that uses the Model Context Protocol (MCP) to give an LLM the ability to manage documents on your filesystem. Ask questions, reference documents with @, and run commands like /summarize — all from your terminal.

How It Works

The app starts an MCP server as a subprocess and connects to it over stdio. When you send a message, it's forwarded to OpenAI with the MCP tools (read, create, edit, delete documents) available as function calls. The LLM decides which tools to invoke, and the results are streamed back to you.

You → CLI → OpenAI (with MCP tools) → MCP Server → Filesystem

Prerequisites

• Python 3.10+
• An OpenAI API key

Setup

1. Configure environment variables

Copy or edit .env in the project root:

OPENAI_API_KEY="sk-..."
OPENAI_MODEL="gpt-4o"
USE_UV=1

Variable	Description
OPENAI_API_KEY	Your OpenAI API key (required)
OPENAI_MODEL	Model to use, e.g. gpt-4o (required)
USE_UV	Set to 1 to run the MCP server via uv, 0 for plain python

2. Install dependencies

With uv (recommended):

pip install uv
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e .

Without uv:

python -m venv .venv
source .venv/bin/activate
pip install -e .

3. Run

python main.py

Or with uv:

uv run main.py

Usage

Chatting

Type a message and press Enter:

> What files do I have?

Referencing documents

Use @filename to include a document's content in your query. Filenames with spaces work too:

> Summarize @pokemon.md
> What's in @Family Tree.pdf

Tab completion activates after typing @. The dropdown includes files from the default mcp_documents/ directory and any directories you've granted access to.

Commands

Type / to see available commands. Commands take a document ID as the first argument:

Command	Syntax	Description
/summarize	/summarize <doc>	Summarize a document
/format	/format <doc>	Reformat a document to markdown
/rewrite	/rewrite <doc> <tone>	Rewrite in a different tone (formal, casual, concise, technical, persuasive, simple)
/convert	/convert <doc> <format>	Convert to another format (json, csv, markdown, yaml, xml, html, plain text)

> /summarize pokemon.md
> /format pokemon.md
> /rewrite pokemon.md formal
> /convert pokemon.csv json

Tab completion works for commands, document names, and tone/format values.

Custom root directories

Point the server at specific directories with --roots:

python main.py --roots ~/my_docs ./data

Additional MCP servers

Load extra MCP server scripts as positional arguments:

python main.py my_server.py another_server.py

File access permissions

When you reference a file outside the allowed directories (--roots or default mcp_documents/), a permission prompt appears:

The MCP server wants to access:
/Users/prem/Desktop/secret.txt
This path is outside the allowed directories.
Allow access? (1=Allow Once, 2=Always Allow, 3=Deny): 

• Allow Once (1) — grants access for this single operation
• Always Allow (2) — grants access for the rest of the session, and adds the parent directory to the allowed list so other files in the same folder are accessible via @ without further prompts
• Deny (3) — blocks access

After "Always Allow", the @ tab-completion dropdown refreshes to include files from the newly allowed directory.

Files are checked for existence before the permission prompt, so you won't be prompted for files that don't exist.

MCP Server

The built-in server (mcp_server.py) exposes:

Tools

Tool	Description
read_doc_contents	Read a document's contents
create_doc	Create a new document
edit_doc_contents	Replace text within a document
delete_doc	Delete a document
allow_path	Grant access to a file path (called by the client after permission is granted)

Resources

URI	Returns
docs://list	All filenames in the documents directory and any allowed directories
docs://recent	5 most recently modified files
docs://file/{filename}	Contents of a specific file

Prompts

Prompt	Syntax	Description
/summarize	/summarize <doc>	Summarize a document and return the result in chat
/format	/format <doc>	Reformat a document to markdown and return the result in chat
/rewrite	/rewrite <doc> <tone>	Rewrite in a different tone and return the result in chat
/convert	/convert <doc> <format>	Convert between formats and return the result in chat

Project Structure

├── main.py              # Entry point — parses args, starts MCP clients and CLI
├── mcp_client.py        # MCP client wrapper (connects to servers via stdio)
├── mcp_server.py        # MCP server with tools, resources, prompts, and permission checks
├── core/
│   ├── cli.py           # Terminal UI (prompt-toolkit, tab completion, key bindings)
│   ├── cli_chat.py      # CLI chat logic (@mentions, /commands, permission handling)
│   ├── chat.py          # Base chat loop (LLM ↔ tool execution cycle)
│   ├── llm.py           # OpenAI API wrapper
│   └── tools.py         # Converts MCP tools to OpenAI function-calling format
├── mcp_documents/       # Sample documents directory
├── pyproject.toml       # Project metadata and dependencies
└── .env                 # API keys and config

Adding documents

Place files in mcp_documents/ (or a custom --roots directory). The server reads from there by default. Supported formats are any text-based file.

To add documents programmatically, use the create_doc tool through the chat interface.