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

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:

> /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

Resources

Prompts

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.