MCP Chat

mcp_starter_project is a command-line chat application built around a local MCP server. The project supports two usage modes:

• Anthropic Claude mode using main.py

• Google Gemini / GenAI mode using genai_main.py

Both modes share the same MCP server implementation and document tooling in mcp_server.py, but use different model adapters and entrypoints.

Runtime modes

Related MCP server: MCP Filesystem Agent v3

Prerequisites

• Python 3.10+

• Either Anthropic or Google Gemini credentials

• Optional: uv if you want to run the MCP server with uv run

Setup

1. Configure environment variables

Create a .env file in the project root with the values for the mode you want to use.

Claude mode

ANTHROPIC_API_KEY="your_api_key_here"
CLAUDE_MODEL="claude-3.5-mini"

Gemini / GenAI mode

GOOGLE_API_KEY="your_google_api_key"
GEMINI_MODEL="gemini-3.1-flash-lite"

Optionally set USE_UV=1 if you want main.py to launch mcp_server.py through uv run instead of the current Python interpreter.

2. Install dependencies

Use the provided pyproject.toml dependencies.

Recommended:

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

If you do not want to install editable mode:

pip install anthropic python-dotenv prompt-toolkit "mcp[cli]>=1.8.0"

Running the application

Choose one of the two supported runtime modes.

Claude mode

python main.py

If you set USE_UV=1, main.py will start mcp_server.py through uv run.

You can also pass additional MCP server scripts to main.py:

python main.py another_server.py

Gemini / GenAI mode

python genai_main.py

This path uses the Google Gemini adapter and the GenAI-specific CLI.

How it works

• main.py starts the CLI app and launches mcp_server.py as a local MCP server.

• mcp_client.py manages the MCP session and exposes methods for listing tools, prompts, and reading resources.

• mcp_server.py defines documents, MCP tools, resources, and a prompt that can be executed through the MCP protocol.

• core/cli.py provides the interactive prompt with / command completion and @ document ID completion.

Usage

Basic chat

Type a question and press Enter.

Reference documents

Use @<document_id> to include a document into your query. For example:

> Tell me about @deposition.md

The CLI will fetch the referenced document content from the MCP server and include it in the model prompt.

Commands

Use / followed by a prompt name to run a server-side prompt. For example, if the MCP server defines a prompt named format, type:

> /format deposition.md

Tab completion is available for prompt names and document IDs.

Project structure

• main.py - application entry point for Anthropic Claude usage

• mcp_client.py - MCP client session wrapper for Claude mode

• genai_main.py - application entry point for Google Gemini / GenAI usage

• genai_mcp_client.py - MCP client session wrapper for GenAI mode

• mcp_server.py - local MCP server with documents, tools, and resources shared by both modes

• core/cli.py - prompt UI with completions and key bindings for Claude mode

• core/cli_chat.py - chat flow, document injection, and MCP prompts for Claude mode

• core/chat.py - general chat orchestration and model invocation for Claude mode

• core/claude.py - Anthropic Claude client wrapper

• core/gemini.py - Gemini model adapter for the GenAI flow

• core/genai_cli.py - CLI prompt UI with completions for GenAI mode

• core/genai_cli_chat.py - GenAI CLI chat flow with MCP-backed resources

• core/genai_chat.py - GenAI chat orchestration and tool loop handling

Development notes

• Add or update documents in the docs dictionary inside mcp_server.py.

• Add new MCP prompts and tools in mcp_server.py to extend the CLI capabilities.

• mcp_client.py already includes MCP session helpers; you can expand it to expose more server operations.