A command-line interface (CLI) AI chat application with Model Context Protocol (MCP) integration for software engineering workflows.
MCP CLI
A command-line interface (CLI) AI chat application with Model Context Protocol (MCP) integration for software engineering workflows.
Inspired by: Anthropic's "Building with Claude API" course - This project extends the concepts taught in the course with production-ready code, comprehensive testing, and practical MCP servers for real-world use cases.
Why Use This Instead of IDE Agents?
Honest answer: For most development work, IDE agents (Kiro, Cursor, GitHub Copilot, etc.) are better—they have full context, can edit directly, and integrate seamlessly into your workflow.
However, this tool has legitimate use cases:
1. MCP Server Development & Testing
- Test custom MCP servers before integrating them into IDEs
- Debug MCP protocol issues in isolation
- Rapid prototyping of new MCP tools and workflows
- Validate tool behavior without IDE complexity
2. Headless & Remote Environments
- SSH sessions where GUI IDEs aren't available
- CI/CD pipelines for automated operations
- Docker containers and server administration
- Remote servers without X11 forwarding
3. Scripting & Automation
- Batch operations via command line
- Shell script integration for automated workflows
- Cron jobs with AI assistance
- Pipeline automation with natural language
4. Learning & Education
- Understand MCP protocol by seeing it in action
- Learn AI tool integration patterns
- Teaching material for MCP development
- Protocol debugging and exploration
5. Terminal-First Workflows
- Lightweight alternative when IDE is overkill
- Quick queries without opening heavy IDE
- Terminal multiplexer (tmux/screen) integration
- Minimal resource usage on constrained systems
Bottom line: If you're doing active development in an IDE, use the IDE agent. Use this for MCP development, automation, remote work, or when you need a lightweight CLI tool.
❌ Not For You If...
- You're actively coding in VS Code, Cursor, or similar IDE → Use the IDE agent instead
- You need full codebase context for refactoring → Use IDE agent
- You want AI to edit files directly → Use IDE agent
- You're doing normal feature development → Use IDE agent
✅ Perfect For You If...
- You're building/testing custom MCP servers
- You're working in SSH/headless environments
- You need CLI automation with AI
- You're learning MCP protocol
- You want a lightweight terminal tool
Features
- Interactive AI Chat: Natural conversation with Claude AI
- Document Management: Reference and edit documents using
@document.mdsyntax - Command Prompts: Execute predefined workflows with
/commandsyntax - Git Integration: Check status, view diffs, commit changes
- File System Operations: Read, write, search files safely
- Code Analysis: Analyze Python code structure, find TODOs, format with Black
- Test Runner: Execute pytest and unittest tests
- Extensible Architecture: Add custom MCP servers for your workflows
When to Use: Practical Comparison
| Scenario | Use IDE Agent | Use MCP Chat | |----------|---------------|--------------| | Active coding in IDE | ✅ Best choice | ❌ Not ideal | | Testing custom MCP server | ❌ Overkill | ✅ Perfect fit | | SSH session (no GUI) | ❌ Not available | ✅ Only option | | CI/CD automation | ❌ Not practical | ✅ Designed for this | | Learning MCP protocol | ⚠️ Too abstracted | ✅ See it directly | | Quick terminal query | ⚠️ Heavy | ✅ Lightweight | | Code review in IDE | ✅ Best choice | ❌ Not ideal | | Batch file operations | ❌ Manual | ✅ Scriptable |
Recommendation: Use IDE agents for development. Use this for MCP development, automation, remote work, or terminal-first workflows.
Prerequisites
- Python 3.9+
- Anthropic API Key
Setup
Step 1: Configure the environment variables
- Create or edit the
.envfile in the project root and verify that the following variables are set correctly:
ANTHROPIC_API_KEY="" # Enter your Anthropic API secret key
Step 2: Install dependencies
Option 1: Setup with uv (Recommended)
uv is a fast Python package installer and resolver.
- Install uv, if not already installed:
pip install uv
- Create and activate a virtual environment:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
- Install dependencies:
uv pip install -e .
- Run the project
uv run main.py
Option 2: Setup without uv
- Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
- Install dependencies:
pip install anthropic python-dotenv prompt-toolkit "mcp[cli]==1.8.0"
- Run the project
python main.py
Usage
Basic Chat
Simply type your message and press Enter:
> What's the difference between async and await in Python?
Document References
Use @ to reference documents in your queries:
> Summarize the key points in @deposition.md
> Compare @report.pdf with @outlook.pdf
Command Prompts
Use / to execute predefined workflows:
> /summarize deposition.md
> /format_document plan.md
Commands auto-complete with Tab.
Using MCP Servers
Git Operations
# Run with Git MCP server
python main.py servers/mcp_git_server.py
# Then in chat:
> Use git_status to show me what files have changed
> Use git_diff to show me the changes in detail
> Use git_log to show recent commits
File System Operations
# Run with File System MCP server
python main.py servers/mcp_filesystem_server.py
# Then in chat:
> Use read_file to show me the contents of main.py
> Use search_files to find all Python files
> Use list_directory to show what's in the core folder
Code Analysis
# Run with Code Analysis MCP server
python main.py servers/mcp_code_analysis_server.py
# Then in chat:
> Use analyze_python_file to analyze core/chat.py
> Use find_todos to find all TODO comments
> Use count_lines to count lines in the core directory
Test Runner
# Run with Test Runner MCP server
python main.py servers/mcp_test_runner_server.py
# Then in chat:
> Use run_pytest to run all tests
> Use list_tests to show available tests
Multiple Servers
Run multiple MCP servers simultaneously:
python main.py servers/mcp_git_server.py servers/mcp_filesystem_server.py servers/mcp_code_analysis_server.py
Real-World Use Cases
Use Case 1: Testing Your Custom MCP Server
You're developing a new MCP server for database operations:
# Test your server in isolation
python main.py servers/mcp_database_server.py
# In chat, test each tool:
> Use db_query with sql="SELECT * FROM users LIMIT 5"
> Use db_schema with table="users"
# Debug issues without IDE complexity
# Iterate quickly on tool definitions
Why not IDE? You need to test the MCP protocol itself, not integrate it yet.
Use Case 2: CI/CD Pipeline Automation
In your GitHub Actions workflow:
- name: Analyze code changes
run: |
echo "Use git_diff to show changes" | python main.py servers/mcp_git_server.py
echo "Use find_todos to check for new TODOs" | python main.py servers/mcp_code_analysis_server.py
echo "Use run_pytest with coverage=true" | python main.py servers/mcp_test_runner_server.py
Why not IDE? No GUI in CI/CD, need scriptable automation.
Use Case 3: Remote Server Administration
SSH'd into a production server:
# No GUI available, but need AI assistance
python main.py servers/mcp_filesystem_server.py
> Use search_files with pattern="**/*.log" to find all log files
> Use read_file with file_path="app.log" to check errors
> Analyze the error patterns and suggest fixes
Why not IDE? No GUI, terminal-only environment.
Use Case 4: Learning MCP Protocol
Teaching a workshop on MCP development:
# Students can see exactly what's happening
python main.py servers/mcp_git_server.py
# Watch the protocol in action
# See tool definitions
# Understand request/response flow
Why not IDE? Need to see the protocol directly, not abstracted.
Development
Running Tests
# Install dev dependencies
uv pip install -e ".[dev]"
# Run all tests
pytest
# Run with coverage
pytest --cov --cov-report=term-missing
# Run specific test file
pytest tests/test_config.py
Code Quality
# Format code with Black
black .
# Lint with Ruff
ruff check .
Adding New Documents
Edit mcp_server.py and add entries to the docs dictionary:
docs = {
"your_doc.md": "Your document content here",
}
Creating Custom MCP Servers
Create a new file servers/mcp_custom_server.py:
from pydantic import Field
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("CustomMCP", log_level="ERROR")
@mcp.tool(
name="your_tool",
description="Description of what your tool does",
)
def your_tool(
param: str = Field(description="Parameter description")
) -> str:
"""Tool implementation."""
return f"Result: {param}"
if __name__ == "__main__":
mcp.run(transport="stdio")
Then run with:
python main.py servers/mcp_custom_server.py
Architecture
mcp-chat/
├── core/ # Core application modules
│ ├── chat.py # Core chat logic
│ ├── claude.py # Claude API wrapper
│ ├── cli.py # CLI interface
│ ├── cli_chat.py # CLI-specific chat features
│ ├── config.py # Configuration management
│ ├── exceptions.py # Custom exceptions
│ ├── logger.py # Logging setup
│ └── tools.py # Tool execution
├── servers/ # MCP servers
│ ├── mcp_server.py # Document server
│ ├── mcp_git_server.py # Git operations
│ ├── mcp_filesystem_server.py # File system
│ ├── mcp_code_analysis_server.py # Code analysis
│ └── mcp_test_runner_server.py # Test runner
├── tests/ # Test suite
├── docs/ # Documentation
│ ├── HONEST_ASSESSMENT.md # When to use this tool
│ ├── QUICK_START.md # 5-minute setup
│ ├── ARCHITECTURE.md # Technical details
│ └── CONTRIBUTING.md # Development guide
├── main.py # Application entry point
├── mcp_client.py # MCP client implementation
└── README.md # This file
Security
- API keys are loaded from
.env(never commit this file) - File system operations are restricted to project directory
- Input validation on all MCP tool parameters
- Proper error handling throughout
Troubleshooting
"ANTHROPIC_API_KEY cannot be empty"
Ensure your .env file exists and contains:
ANTHROPIC_API_KEY="your-actual-api-key"
"Git is not installed"
Install Git for your platform: https://git-scm.com/downloads
"pytest is not installed"
Install dev dependencies:
uv pip install -e ".[dev]"
MCP Server Connection Issues
Check that the server script exists and is executable. Enable debug logging:
LOG_LEVEL=DEBUG python main.py
FAQ
Q: Should I use this instead of Kiro/Cursor/GitHub Copilot?
A: No, for active development in an IDE, use the IDE agent. They have full context, can edit directly, and integrate better. Use this tool for:
- Testing custom MCP servers
- Headless/SSH environments
- CI/CD automation
- Learning MCP protocol
Q: What's the main advantage of this tool?
A: Direct MCP protocol access. You can test and debug MCP servers without IDE complexity, automate with scripts, and work in terminal-only environments.
Q: Can this replace my IDE?
A: No. This is a specialized tool for specific use cases, not a general-purpose development environment.
Q: When would I actually use this?
A: Real scenarios:
- You're building a custom MCP server and need to test it
- You're SSH'd into a server with no GUI
- You're writing a CI/CD pipeline that needs AI assistance
- You're teaching/learning MCP protocol
- You need a lightweight CLI tool for quick queries
Q: Is this production-ready?
A: Yes, for its intended use cases. It has comprehensive tests, error handling, and security. But remember: it's a CLI tool, not an IDE replacement.
Q: Why did you build this?
A: Legitimate reasons:
- MCP server development needs isolated testing
- Headless environments need AI assistance
- Automation pipelines benefit from natural language
- Learning MCP protocol requires seeing it directly
Contributing
We welcome contributions! See docs/CONTRIBUTING.md for detailed guidelines.
Quick start:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass:
pytest - Format code:
black . - Submit a pull request
Credits
This project was inspired by Anthropic's "Building with Claude API" course. The course provides excellent foundational knowledge about working with Claude and MCP. This project extends those concepts with:
- Production-ready code with comprehensive error handling
- Full test suite with 23+ tests
- Security hardening and input validation
- Practical MCP servers for real-world use cases
- Professional documentation and architecture
Special thanks to the Anthropic team for their educational resources and the MCP protocol.
License
MIT License - see LICENSE file for details.
Documentation
- Quick Start Guide - Get started in 5 minutes
- Architecture - Technical details
- Contributing - Development guide
Support
- Issues: GitHub Issues
- Documentation: See
docs/directory - Questions: Open a discussion or issue