Mcp-Agent

4 hours ago 1

A powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.

Multiple AI Backends: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility
MCP Model Server: Expose all AI models as standardized MCP tools with persistent conversations
Modular Architecture: Provider-model separation with centralized base agent for maximum flexibility
MCP Server Integration: Connect to multiple MCP servers for extended functionality
Persistent Conversations: Maintain conversation context across multiple tool calls for each AI model
Interactive Chat: Real-time conversation with AI models and comprehensive tool access
Subagent System: Spawn focused subagents for complex tasks with automatic coordination
Command-Line Tools: Manage MCP servers and query models directly
Built-in Tools: File operations, bash execution, web fetching, todo management, and task delegation
Enhanced Tool Display: Full parameter visibility and complete response output (no truncation)

Clone the repository:

git clone https://github.com/amranu/mcp-agent.git cd mcp-agent
Install the package:
Configure API keys (environment variables):

# Set environment variables for the providers you want to use export OPENAI_API_KEY=your_openai_api_key_here export DEEPSEEK_API_KEY=your_deepseek_api_key_here export ANTHROPIC_API_KEY=your_anthropic_api_key_here export GEMINI_API_KEY=your_gemini_api_key_here export OPENROUTER_API_KEY=your_openrouter_api_key_here # Start with automatic provider selection agent chat # Or specify a particular provider-model combination agent chat --model openai:gpt-4-turbo-preview

Smart Provider Selection: The agent automatically selects a configured provider based on available API keys.

Configuration is automatically saved to ~/.config/mcp-agent/config.json and persists across sessions.

Start an interactive chat session with your configured AI model and MCP tools:

agent chat --model deepseek:deepseek-chat

Start the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:

# Start via stdio transport (recommended for MCP clients) python mcp_server.py --stdio # Or start via agent CLI (defaults to stdio) agent mcp serve agent mcp serve --stdio # explicit stdio # Start with TCP transport (useful for debugging) python mcp_server.py --tcp --port 3000 --host localhost agent mcp serve --tcp --port 3000 --host localhost

The model server exposes AI models from 5 providers:

Anthropic: Claude models
OpenAI: GPT models
DeepSeek: Chat and reasoning models
Gemini: Google's Gemini models
OpenRouter: Multi-provider access

# Format: name:command:arg1:arg2:... agent mcp add myserver:node:/path/to/server.js agent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:. # Add the AI models server to your MCP configuration agent mcp add ai-models:python:mcp_server.py:--stdio

agent mcp remove myserver

Ask a one-time question without entering interactive mode:

agent ask "What's the weather like today?"

Switch between different AI models using the provider-model format (configuration persists automatically):

# Provider-model format switching agent switch anthropic:claude-3.5-sonnet agent switch openai:gpt-4-turbo-preview agent switch deepseek:deepseek-chat agent switch gemini:gemini-2.5-flash

Or use slash commands within interactive chat:

/switch anthropic:claude-3.5-sonnet /switch openai:gpt-4-turbo-preview /switch deepseek:deepseek-reasoner /switch gemini:gemini-2.5-pro

Persistent Configuration System

The agent uses an automatic persistent configuration system that saves settings to ~/.config/mcp-agent/config.json:

API Keys: Set via environment variables
Model Preferences: Automatically saved when using switch commands
MCP Servers: Managed through the CLI and persisted across sessions
Tool Permissions: Configurable with session-based approval system

Configure the agent through environment variables:

# Anthropic Configuration (required for Claude models) ANTHROPIC_API_KEY=your_key_here ANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022 ANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7 # OpenAI Configuration (required for GPT models) OPENAI_API_KEY=your_key_here OPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview OPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7 # DeepSeek Configuration (required for DeepSeek models) DEEPSEEK_API_KEY=your_key_here DEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat DEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6 # Gemini Configuration (required for Gemini models) GEMINI_API_KEY=your_key_here GEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash GEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7 # OpenRouter Configuration (optional for multi-provider access) OPENROUTER_API_KEY=your_key_here OPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional OPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7 # Provider-Model Selection (new format) DEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat # Subagent Configuration SUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false # Host Configuration (optional) HOST_NAME=mcp-agent # defaults to 'mcp-agent' LOG_LEVEL=INFO # defaults to INFO

Configuration changes made via commands (like model switching) are automatically persisted and don't require manual .env file editing.

The agent comes with comprehensive built-in tools:

File Operations: Read, write, edit, and search files with surgical precision
Directory Operations: List directories, get current path, navigate filesystem
Shell Execution: Run bash commands with full output capture
Web Fetching: Download and process web content
Todo Management: Organize and track tasks across sessions
Task Delegation: Spawn focused subagents for complex or context-heavy tasks
Text Processing: Search, replace, and manipulate text content

AI Model Tools (via MCP Server)

All model tools support:

Persistent Conversations: Maintain context across calls
Conversation Management: Create, continue, or clear conversations
Full Parameter Control: Temperature, max_tokens, system prompts

🔍 Interactive Chat Commands

Within the interactive chat, use these slash commands:

/help - Show available commands
/tools - List all available tools
/clear - Clear conversation history
/model - Show current model
/tokens - Show token usage
/compact - Compact conversation history
/switch <provider>:<model> - Switch to any provider-model combination
/task - Spawn a subagent for complex tasks

Example: Basic File Operations

agent chat --model deepseek:deepseek-chat

In chat:

You: List all files in this directory You: Read the contents of agent.py You: Create a new file called hello.py with a simple function

Example: System Operations

In chat:

You: Show me the current directory You: Run "git status" to check repository status You: What's the disk usage of this folder?

Example: Subagent Task Delegation

For complex or context-heavy tasks, delegate to focused subagents:

You: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies You: Can you analyze this large log file and find any error patterns? [Agent automatically spawns subagent for file analysis]

Subagents work independently and automatically return results to the main conversation.

Provider-Model Architecture

┌─────────────────┐ │ CLI Interface │ │ (agent.py) │ └─────────┬───────┘ │ ▼ ┌─────────────────────┐ ┌─────────────────────────────────────────┐ │ MCPHost │◄───│ Provider + Model │ │ (BaseLLMProvider) │ │ Composition │ └─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ BaseProvider │ │ ModelConfig │ │ ▼ │ │ Subclasses: │ │ Subclasses: │ │ ┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │ │ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │ │ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │ │ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │ └─────────┬───────────┘ │ │ • OpenRouter │ │ │ │ │ │ └─────────────────┘ └─────────────────┘ │ ▼ └─────────────────────────────────────────┘ ┌─────────────────────┐ │ │ BaseMCPAgent │ ▼ │ (Abstract base) │ ┌─────────────────┐ └─────────┬───────────┘ │ Tool Converters │ │ │ • OpenAI Format │ ┌─────────▼───────────┐ │ • Anthropic │ │ Core Components: │ │ • Gemini │ │ • SubagentCoordinator│ └─────────────────┘ │ • BuiltinToolExecutor│ │ • ChatInterface │ ┌─────────────────┐ │ • SlashCommands │◄───────────────│ Built-in Tools │ │ • ToolExecutionEngine│ │ • File Ops │ │ • TokenManager │ │ • Bash Execute │ │ • SystemPromptBuilder│ │ • Web Fetch │ │ • MessageProcessor │ │ • Todo Mgmt │ └─────────┬───────────┘ │ • Task Spawn │ │ │ • Glob/Grep │ ▼ │ • MultiEdit │ ┌─────────────────────┐ └─────────────────┘ │ External MCP Servers │ │ • AI Model Server │ ┌─────────────────┐ │ • File System │ │ Subagent System │ │ • APIs & Databases │ │ • Focused Tasks │ │ • Custom Tools │ │ • Auto Cleanup │ └─────────────────────┘ │ • Event-Driven │ └─────────────────┘

Key Architectural Benefits

Provider-Model Separation: API providers decoupled from model characteristics
MCP Model Server: Standardized access to all AI models via MCP protocol
Persistent Conversations: Conversation context maintained across tool calls
Easy Extensibility: Adding new providers or models requires minimal code
Robust Tool Integration: Unified tool execution with provider-specific optimizations
Intelligent Subagent System: Automatic task delegation and coordination
Multi-Provider Access: Same model accessible through different providers
Enhanced Visibility: Full parameter display and complete response output

Please read our CONTRIBUTING.md file for more details on our code of conduct and the process for submitting pull requests.

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Add tests if applicable
Commit your changes: git commit -m 'Add feature'
Push to the branch: git push origin feature-name
Submit a pull request

Python 3.10+
API keys for desired providers:
- Anthropic API key (for Claude models)
- OpenAI API key (for GPT models)
- DeepSeek API key (for DeepSeek models)
- Google AI Studio API key (for Gemini models)
- OpenRouter API key (for multi-provider access)
FastMCP for MCP server functionality
Node.js (for MCP servers that require it)

API Keys: Stored as environment variables
Configuration: Automatically managed in user home directory (~/.config/mcp-agent/)
MCP Servers: Local configurations with session-based tool permissions
Tool Execution: Built-in permission system for sensitive operations
Subagent Isolation: Subagents run in controlled environments with specific tool access
Subagent Permissions: Can be configured to bypass permission checks for automated workflows via SUBAGENT_PERMISSIONS_BYPASS=true

This project is licensed under the MIT License - see the LICENSE file for details.