Claude Code Control MCP Server
Claude Code automation and control for agentic workflows.
Part of the Agentic System - a 24/7 autonomous AI framework with persistent memory.
Programmatic task execution using Claude AI for autonomous coding workflows.
Overview
The Claude Code Control MCP enables programmatic code task execution through the Model Context Protocol. It provides a bridge for AI agents and workflows to execute coding tasks using Claude Sonnet 4.5, with comprehensive file tracking, command execution, and status monitoring.
Features
- Programmatic Task Execution: Execute natural language coding tasks autonomously
- File Operations: Read, write, edit, and track file changes
- Code Search: Grep-like search across codebases
- Command Execution: Run shell commands with output capture
- Change Tracking: Monitor all file modifications during execution
- Status Monitoring: Real-time execution status and history
Architecture
┌─────────────────────────────────────────────────────────┐
│ MCP Client (Claude Code) │
└────────────────────┬────────────────────────────────────┘
│ MCP Protocol
┌────────────────────▼────────────────────────────────────┐
│ Claude Code Control MCP Server │
│ ┌──────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ Server │ │ Executor │ │ Tracker │ │
│ │ (MCP) │ │ (Claude AI) │ │ (Files) │ │
│ └──────────────┘ └───────────────┘ └─────────────┘ │
└────────────────────┬────────────────────────────────────┘
│ Anthropic API
┌────────────────────▼────────────────────────────────────┐
│ Claude Sonnet 4.5 (Anthropic API) │
└─────────────────────────────────────────────────────────┘
Installation
- Install dependencies:
cd ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/mcp-servers/claude-code-control-mcp
pip3 install -r requirements.txt
- Set API key:
export ANTHROPIC_API_KEY="sk-ant-..."
- Register with Claude Code:
Add to ~/.claude.json:
{
"mcpServers": {
"claude-code-control": {
"command": "python3",
"args": [
"${AGENTIC_SYSTEM_PATH:-/opt/agentic}/mcp-servers/claude-code-control-mcp/server.py"
],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
},
"disabled": false
}
}
}
- Restart Claude Code:
# Exit current session and restart
MCP Tools
execute_code_task
Execute a coding task using Claude AI with autonomous tool use.
Input:
{
"task_description": "Add error handling to the API endpoint in server.py",
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}/api",
"context_files": ["server.py", "tests/test_api.py"],
"max_iterations": 20
}
Output:
{
"success": true,
"task_description": "Add error handling...",
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}/api",
"iterations": 8,
"tool_uses": [
{
"tool": "read_file",
"input": {"path": "server.py"},
"result": "File content..."
}
],
"file_changes": {
"total_changes": 2,
"files_modified": ["server.py"],
"files_created": [],
"files_deleted": []
},
"duration_seconds": 12.5,
"final_message": "Successfully added error handling..."
}
read_codebase
Read and analyze multiple files using glob patterns.
Input:
{
"patterns": ["*.py", "src/**/*.ts"],
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}",
"max_files": 50
}
Output:
{
"files_read": 12,
"files": [
{
"path": "server.py",
"size": 2048,
"content": "#!/usr/bin/env python3..."
}
]
}
search_code
Search for code patterns across the codebase.
Input:
{
"query": "async def.*execute",
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}",
"file_pattern": "*.py",
"case_sensitive": true,
"max_results": 100
}
Output:
{
"query": "async def.*execute",
"total_matches": 5,
"matches": [
"executor.py:42:async def execute_task(...)",
"server.py:156:async def execute_command(...)"
]
}
modify_files
Modify multiple files with batch operations.
Input:
{
"changes": [
{
"path": "config.py",
"action": "write",
"content": "DEBUG = True\n"
},
{
"path": "server.py",
"action": "edit",
"old_content": "port = 8080",
"new_content": "port = 9000"
}
],
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}"
}
Output:
{
"modifications": [
{"path": "config.py", "status": "written"},
{"path": "server.py", "status": "edited"}
],
"file_changes": {
"total_changes": 2,
"files_created": ["config.py"],
"files_modified": ["server.py"]
}
}
run_commands
Execute shell commands with output capture.
Input:
{
"commands": [
"python3 -m pytest tests/",
"black --check *.py"
],
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}",
"timeout": 30
}
Output:
{
"command_results": [
{
"command": "python3 -m pytest tests/",
"exit_code": 0,
"stdout": "===== 5 passed in 2.5s =====",
"stderr": ""
},
{
"command": "black --check *.py",
"exit_code": 0,
"stdout": "All done! ✨",
"stderr": ""
}
]
}
get_execution_status
Get status of current or recent execution.
Input:
{
"include_history": true
}
Output:
{
"current_execution": {
"task_description": "Add error handling...",
"success": true,
"iterations": 8
},
"executor_initialized": true,
"execution_history": [...]
}
Usage Examples
Example 1: Automated Code Refactoring
# Using from Python with anthropic client
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=4096,
tools=[...], # MCP tools from claude-code-control
messages=[{
"role": "user",
"content": "Refactor the authentication module to use async/await"
}]
)
Example 2: Autonomous Bug Fixing
# Using from Claude Code
claude --prompt "Fix the memory leak in server.py using the claude-code-control MCP"
Example 3: Integration Testing
# Using from workflow automation
from anthropic import Anthropic
client = Anthropic()
# Execute task
result = await mcp_execute_tool(
"execute_code_task",
{
"task_description": "Add integration tests for the API endpoints",
"working_directory": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}/api",
"context_files": ["server.py", "models.py"]
}
)
print(f"Tests created: {result['file_changes']['files_created']}")
Integration Points
Temporal Workflows
@workflow.defn
class CodeTaskWorkflow:
@workflow.run
async def run(self, task_description: str) -> dict:
# Execute code task via MCP
result = await workflow.execute_activity(
execute_via_mcp,
args=[task_description],
start_to_close_timeout=timedelta(minutes=5)
)
return result
n8n Workflows
Use HTTP Request node to call MCP server:
{
"method": "POST",
"url": "http://localhost:PORT/execute",
"body": {
"tool": "execute_code_task",
"arguments": {
"task_description": "{{$json.task}}"
}
}
}
Intelligent Agents
from intelligent_agents.sdk_agents import ClaudeAgent
agent = ClaudeAgent()
# Agent uses MCP tools automatically
result = agent.execute(
"Refactor authentication to use OAuth2",
mcp_tools=["claude-code-control"]
)
File Tracking
The MCP server tracks all file changes during execution:
- Created files: New files written
- Modified files: Existing files changed
- Deleted files: Files removed
- Read files: Files accessed for reading
Changes include:
- File hashes (SHA256)
- Size changes
- Timestamps
- Line change statistics (when available)
Error Handling
The server handles errors gracefully:
- Tool execution errors: Returned with error details
- File operation errors: Logged and returned to caller
- Command execution errors: Exit codes and stderr captured
- API errors: Anthropic API errors propagated with context
Security Considerations
- API Key Management: Store
ANTHROPIC_API_KEYsecurely - File Access: Limited to specified working directories
- Command Execution: Shell commands run with user permissions
- Input Validation: All inputs validated before execution
- Output Sanitization: Sensitive data filtered from outputs
Performance
- Typical task execution: 5-30 seconds
- File operations: < 1 second per file
- Code search: < 5 seconds for large codebases
- Memory usage: ~50-100MB during execution
Troubleshooting
Server won't start
# Check API key
echo $ANTHROPIC_API_KEY
# Test server directly
python3 server.py
# Check logs
tail -f ~/.claude/logs/mcp-servers.log
Tool execution fails
# Verify dependencies
pip3 list | grep anthropic
pip3 list | grep mcp
# Test executor
python3 test_executor.py
File tracking issues
# Check permissions
ls -la ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/
# Verify working directory
pwd
Development
Running Tests
cd ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/mcp-servers/claude-code-control-mcp
python3 test_server.py
Adding New Tools
- Add tool definition to
list_tools() - Implement handler in
call_tool() - Update documentation
- Add tests
Debugging
Enable debug logging:
logging.basicConfig(level=logging.DEBUG)
Roadmap
- Batch task execution
- Task queuing and scheduling
- Integration with enhanced-memory MCP
- Code analysis tools (complexity, coverage)
- Git integration (commit, push, PR creation)
- Multi-file refactoring support
- Streaming execution updates
- Web UI for monitoring
Contributing
Contributions welcome! Areas for improvement:
- Additional tool implementations
- Performance optimizations
- Enhanced error handling
- Documentation improvements
- Test coverage
License
Part of the agentic-system project. See main LICENSE file.
Support
For issues and questions:
- Check logs:
~/.claude/logs/ - Review MCP documentation: https://modelcontextprotocol.io
- Anthropic API docs: https://docs.anthropic.com
Related Documentation
Part of the MCP Ecosystem
This server integrates with other MCP servers for comprehensive AGI capabilities:
| Server | Purpose |
|---|---|
| enhanced-memory-mcp | 4-tier persistent memory with semantic search |
| agent-runtime-mcp | Persistent task queues and goal decomposition |
| agi-mcp | Full AGI orchestration with 21 tools |
| cluster-execution-mcp | Distributed task routing across nodes |
| node-chat-mcp | Inter-node AI communication |
| ember-mcp | Production-only policy enforcement |
See agentic-system-oss for the complete framework.