# Claude Agent Toolkit
**Simplified AI agent development with decorator-based tools and external MCP server integration**
A Python framework that solves the complexity of claude-code-sdk tool integration through an intuitive decorator-based approach. Created to provide a stable, consistent development experience similar to Google's Agent Development Kit (ADK), this toolkit enables effortless creation of Claude Code agents with custom MCP tools and seamless integration with existing MCP servers.
## Table of Contents
- [Why Claude Agent Toolkit?](#why-claude-agent-toolkit)
- [When Should You Use This?](#when-should-you-use-this)
- [Quick Start](#quick-start)
- [Installation & Setup](#installation--setup)
- [Usage Examples](#usage-examples)
- [Core Features](#core-features)
- [Architecture](#architecture)
- [Built-in Tools](#built-in-tools)
- [Creating Custom Tools](#creating-custom-tools)
- [FAQ](#faq)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
## Why Claude Agent Toolkit?
### The Problem
Working directly with claude-code-sdk presents two major challenges:
1. **Complex Tool Integration** - Manual MCP server setup, connection handling, and tool registration
2. **Inconsistent Execution** - Different local environments causing unpredictable behavior
### The Solution
Claude Agent Toolkit solves these issues through:
- **🎯 Decorator-Based Tools** - Simple `@tool` decorator converts any Python function into a Claude-compatible tool
- **🐳 Isolated Execution** - Docker containers ensure consistent behavior across all environments
- **⚡ Zero Configuration** - Automatic MCP server management and tool discovery
*"An intuitive and stable development experience similar to Google's ADK"* - [Cheolwan Park, Creator](https://blog.codingvillain.com/post/claude-agent-toolkit)
### Before vs After
**Before (Direct claude-code-sdk):**
```python
# Complex MCP server setup
# Manual connection management
# Environment-specific configurations
# Inconsistent tool behavior
```
**After (Claude Agent Toolkit):**
```python
class CalculatorTool(BaseTool):
@tool(description="Adds two numbers together")
async def add(self, a: float, b: float) -> dict:
return {"result": a + b}
agent = Agent(tools=[CalculatorTool()])
```
## When Should You Use This?
> **Update**: Recent updates to claude-code-sdk have simplified tool addition significantly. This has substantially reduced the necessity for Claude Agent Toolkit compared to when it was first created.
### Use claude-code-sdk When:
- Building simple agents with basic tooling needs
- Rapid prototyping and experimentation
- Utilizing local environment configurations
- Working with subprocess execution only
### Use Claude Agent Toolkit When:
- **Isolated Execution Required** - Docker containers for production consistency
- **CPU-Intensive Tools** - Parallel execution in separate process pools with `parallel=True`
- **Production Environments** - Consistent execution across different deployments
- **Complex Tool Orchestration** - Multiple tools with state management
### Quick Comparison
| Feature | claude-code-sdk | Claude Agent Toolkit |
|---------|----------------|---------------------|
| **Setup Complexity** | Simple (recent updates) | Minimal with decorators |
| **Execution** | Same process | Docker/Subprocess isolation |
| **CPU-Intensive Tasks** | Blocking | Parallel with `parallel=True` |
| **Environment Consistency** | Variable | Guaranteed with Docker |
| **Best For** | Prototyping, simple tools | Production, complex tools |
## Quick Start
```python
from claude_agent_toolkit import Agent, BaseTool, tool
# 1. Create a custom tool with @tool decorator
class CalculatorTool(BaseTool):
@tool(description="Adds two numbers together")
async def add(self, a: float, b: float) -> dict:
result = a + b
return {
"operation": f"{a} + {b}",
"result": result,
"message": f"The result of adding {a} and {b} is {result}"
}
# 2. Create and run an agent
async def main():
agent = Agent(
system_prompt="You are a helpful calculator assistant",
tools=[CalculatorTool()],
model="sonnet" # haiku, sonnet, or opus
)
result = await agent.run("What is 15 + 27?")
print(result) # Claude will use your tool and return the answer
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
## Installation & Setup
### Prerequisites
- **Python 3.12+** with `uv` package manager
- **Docker Desktop** (required for Docker executor, recommended)
- **Claude Code OAuth Token** - Get from [Claude Code](https://claude.ai/code)
### Install the Package
```bash
# Using pip
pip install claude-agent-toolkit
# Using uv (recommended)
uv add claude-agent-toolkit
# Using poetry
poetry add claude-agent-toolkit
```
### Set Your OAuth Token
Get your token by running `claude setup-token` in your terminal, then:
```bash
export CLAUDE_CODE_OAUTH_TOKEN='your-token-here'
```
### Quick Verification
```bash
# Clone examples (optional)
git clone https://github.com/cheolwanpark/claude-agent-toolkit.git
cd claude-agent-toolkit/src/examples/calculator
python main.py
```
## Usage Examples
### Basic Agent with Custom Tool
```python
from claude_agent_toolkit import Agent, BaseTool, tool, ExecutorType
class MyTool(BaseTool):
def __init__(self):
super().__init__()
self.counter = 0 # Explicit data management
@tool(description="Increment counter and return value")
async def increment(self) -> dict:
self.counter += 1
return {"value": self.counter}
# Docker executor (default, production-ready)
agent = Agent(tools=[MyTool()])
# Subprocess executor (faster startup, development)
agent = Agent(tools=[MyTool()], executor=ExecutorType.SUBPROCESS)
result = await agent.run("Increment the counter twice")
```
### Model Selection
```python
# Fast and efficient for simple tasks
weather_agent = Agent(
tools=[weather_tool],
model="haiku"
)
# Balanced performance (default)
general_agent = Agent(
tools=[calc_tool, weather_tool],
model="sonnet"
)
# Most capable for complex reasoning
analysis_agent = Agent(
tools=[analysis_tool],
model="opus"
)
# Override per query
result = await weather_agent.run(
"Complex weather pattern analysis",
model="opus"
)
```
### CPU-Intensive Operations
```python
class HeavyComputeTool(BaseTool):
@tool(description="Heavy computation", parallel=True, timeout_s=120)
def process_data(self, data: str) -> dict:
# Sync function - runs in separate process
import time
time.sleep(5) # Simulate heavy work
return {"processed": f"result_{data}"}
```
### Error Handling
```python
from claude_agent_toolkit import (
Agent, BaseTool,
ConfigurationError, ConnectionError, ExecutionError
)
try:
agent = Agent(tools=[MyTool()])
result = await agent.run("Process my request")
except ConfigurationError as e:
print(f"Setup issue: {e}") # Missing token, invalid config
except ConnectionError as e:
print(f"Connection failed: {e}") # Docker, network issues
except ExecutionError as e:
print(f"Execution failed: {e}") # Tool failures, timeouts
```
## Core Features
- **🎯 Decorator-Based Tools** - Transform any Python function into a Claude tool with simple `@tool` decorator
- **🔌 External MCP Integration** - Connect to existing MCP servers via stdio and HTTP transports
- **🐳 Isolated Execution** - Docker containers ensure consistent behavior across all environments
- **⚡ Zero Configuration** - Automatic MCP server management, port selection, and tool discovery
- **🔧 Flexible Execution Modes** - Choose Docker isolation (production) or subprocess (development)
- **📝 Explicit Data Management** - You control data persistence with no hidden state
- **⚙️ CPU-bound Operations** - Process pools for heavy computations with parallel processing
- **🎭 Multi-tool Coordination** - Claude Code intelligently orchestrates multiple tools
- **🏗️ Production Ready** - Built for scalable, reliable agent deployment
## Architecture
### Execution Modes
| Feature | Docker (Default) | Subprocess |
|---------|------------------|------------|
| **Isolation** | Full container isolation | Process isolation only |
| **Setup Time** | ~3 seconds | ~0.5 seconds |
| **Use Case** | Production, testing | Development, CI/CD |
| **Requirements** | Docker Desktop | None |
### Component Overview
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Your Tools │ │ Agent │ │ Claude Code │
│ (MCP Servers) │◄──►│ (Orchestrator) │◄──►│ (Reasoning) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Host Process │ │ Docker Container │ │ Claude Code API │
│ (localhost) │ │ or Subprocess │ │ (claude.ai) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
## External MCP Server Integration
### Connect to Existing MCP Servers
Integrate with any existing MCP server using stdio or HTTP transport:
```python
from claude_agent_toolkit import Agent
from claude_agent_toolkit.tool.mcp import StdioMCPTool, HttpMCPTool
# Connect to an MCP server via command execution
everything_server = StdioMCPTool(
command="npx",
args=["-y", "@modelcontextprotocol/server-everything"],
name="everything"
)
# Connect to an HTTP MCP server
http_server = HttpMCPTool(
url="http://localhost:3001/mcp",
name="my-http-server"
)
# Mix with your custom tools
agent = Agent(
system_prompt="You can use both custom and external tools",
tools=[MyCustomTool(), everything_server, http_server]
)
result = await agent.run("Use the everything server to echo 'Hello World'")
```
### When to Use External MCP Integration
- **Existing MCP Ecosystem**: Leverage community MCP servers and tools
- **Language Diversity**: Use MCP servers written in Node.js, Python, Go, etc.
- **Specialized Tools**: Integrate domain-specific tools without reimplementation
- **Rapid Prototyping**: Quickly test MCP servers before building custom equivalents
- **Service Architecture**: Connect to MCP servers running as microservices
### Supported Transports
| Transport | Use Case | Example |
|-----------|----------|---------|
| **Stdio** | Command-line tools, npm packages | `npx` servers, Python scripts |
| **HTTP** | Web services, microservices | REST APIs, containerized servers |
## Built-in Tools
### FileSystemTool - Secure File Operations
Control exactly what files your agent can access with pattern-based permissions.
```python
from claude_agent_toolkit.tools import FileSystemTool
# Define access patterns
permissions = [
("*.txt", "read"), # Read all text files
("data/**", "write"), # Write to data directory
("logs/*.log", "read"), # Read log files only
]
fs_tool = FileSystemTool(
permissions=permissions,
root_dir="/path/to/workspace" # Restrict to directory
)
agent = Agent(
system_prompt="You are a file manager assistant",
tools=[fs_tool]
)
result = await agent.run(
"List all text files and create a summary in data/report.txt"
)
```
### DataTransferTool - Type-Safe Data Transfer
Transfer structured data between Claude agents and your application using Pydantic models.
```python
from claude_agent_toolkit.tools import DataTransferTool
from pydantic import BaseModel, Field
from typing import List
class UserProfile(BaseModel):
name: str = Field(..., description="Full name")
age: int = Field(..., ge=0, le=150, description="Age in years")
interests: List[str] = Field(default_factory=list)
# Create tool for specific model
user_tool = DataTransferTool.create(UserProfile, "UserProfileTool")
agent = Agent(
system_prompt="You handle user profile data transfers",
tools=[user_tool]
)
# Transfer data through Claude
await agent.run(
"Transfer user: Alice Johnson, age 28, interests programming and hiking"
)
# Retrieve validated data
user_data = user_tool.get()
if user_data:
print(f"Retrieved: {user_data.name}, age {user_data.age}")
```
## Creating Custom Tools
### Basic Tool Pattern
```python
from claude_agent_toolkit import BaseTool, tool
class MyTool(BaseTool):
def __init__(self):
super().__init__() # Server starts automatically
self.data = {} # Explicit data management
@tool(description="Async operation")
async def process_async(self, data: str) -> dict:
# Async operations for I/O, API calls
return {"result": f"processed_{data}"}
@tool(description="CPU-intensive operation", parallel=True, timeout_s=60)
def process_heavy(self, data: str) -> dict:
# Sync function - runs in separate process
# Note: New instance created, self.data won't persist
import time
time.sleep(2)
return {"result": f"heavy_{data}"}
```
### Context Manager Support
```python
# Single tool with guaranteed cleanup
with MyTool() as tool:
agent = Agent(tools=[tool])
result = await agent.run("Process my data")
# Server automatically cleaned up
# Multiple tools
with MyTool() as calc_tool, WeatherTool() as weather_tool:
agent = Agent(tools=[calc_tool, weather_tool])
result = await agent.run("Calculate and check weather")
# Both tools cleaned up automatically
```
## FAQ
### What is Claude Agent Toolkit?
A Python framework that lets you build AI agents using Claude Code with custom tools. Unlike generic agent frameworks, this specifically leverages Claude Code's advanced reasoning capabilities with your existing subscription.
### How is this different from other agent frameworks?
- **Uses Claude Code**: Leverages Claude's production infrastructure and reasoning
- **MCP Protocol**: Industry-standard tool integration, not proprietary APIs
- **Explicit Data**: You control data persistence, no hidden state management
- **Production Focus**: Built for real deployment, not just experiments
### Do I need Docker?
Docker is recommended for production but not required. Use `ExecutorType.SUBPROCESS` for development:
```python
agent = Agent(tools=[my_tool], executor=ExecutorType.SUBPROCESS)
```
### Which model should I use?
- **haiku**: Fast, cost-effective for simple operations
- **sonnet**: Balanced performance, good default choice
- **opus**: Maximum capability for complex reasoning
### How do I handle errors?
The framework provides specific exception types:
```python
from claude_agent_toolkit import ConfigurationError, ConnectionError, ExecutionError
try:
result = await agent.run("task")
except ConfigurationError:
# Missing OAuth token, invalid config
except ConnectionError:
# Docker/network issues
except ExecutionError:
# Tool failures, timeouts
```
### Can I use multiple tools together?
Yes! Claude Code intelligently orchestrates multiple tools:
```python
agent = Agent(tools=[calc_tool, weather_tool, file_tool])
result = await agent.run(
"Calculate the average temperature and save results to report.txt"
)
```
## Testing
The framework is validated through comprehensive examples rather than traditional unit tests. Each example demonstrates specific capabilities and serves as both documentation and validation.
### Run Examples
```bash
# Clone the repository
git clone https://github.com/cheolwanpark/claude-agent-toolkit.git
cd claude-agent-toolkit
# Set your OAuth token
export CLAUDE_CODE_OAUTH_TOKEN='your-token-here'
# Run different examples
cd src/examples/calculator && python main.py # Stateful operations, parallel processing
cd src/examples/weather && python main.py # External API integration
cd src/examples/subprocess && python main.py # No Docker required
cd src/examples/filesystem && python main.py # Permission-based file access
cd src/examples/datatransfer && python main.py # Type-safe data transfer
cd src/examples/mcp && python main.py # External MCP server integration
```
### Example Structure
```
src/examples/
├── calculator/ # Mathematical operations with state management
├── weather/ # External API integration (OpenWeatherMap)
├── subprocess/ # Subprocess executor demonstration
├── filesystem/ # FileSystemTool with permissions
├── datatransfer/ # DataTransferTool with Pydantic models
├── mcp/ # External MCP server integration (stdio, HTTP)
└── README.md # Detailed example documentation
```
### Docker Validation
Examples can run with both executors:
```bash
# Docker executor (default)
python main.py
# Subprocess executor (faster startup)
# Examples automatically use subprocess when Docker unavailable
```
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and validate with examples
4. Run examples to verify functionality
5. Submit a pull request
### Development Setup
```bash
git clone https://github.com/cheolwanpark/claude-agent-toolkit.git
cd claude-agent-toolkit
uv sync --group dev
# Validate your changes by running examples
export CLAUDE_CODE_OAUTH_TOKEN='your-token'
cd src/examples/calculator && python main.py
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
**Created by**: [Cheolwan Park](https://github.com/cheolwanpark) • **Blog**: [Project Background](https://blog.codingvillain.com/post/claude-agent-toolkit)
**Links**: [Homepage](https://github.com/cheolwanpark/claude-agent-toolkit) • [Claude Code](https://claude.ai/code) • [Issues](https://github.com/cheolwanpark/claude-agent-toolkit/issues) • [Model Context Protocol](https://modelcontextprotocol.io/)
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-agent-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Cheolwan Park <cheolwan.park552@gmail.com>",
"keywords": "agent-framework, ai-agents, claude-agent-toolkit, claude-agents, claude-code, docker, mcp-tools, model-context-protocol",
"author": null,
"author_email": "Cheolwan Park <cheolwan.park552@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7a/a2/fc75163e8247cc6be2c5977f77c39b3116fe18165bb3dd591c57cc83d8f2/claude_agent_toolkit-0.2.2.tar.gz",
"platform": null,
"description": "# Claude Agent Toolkit\n\n**Simplified AI agent development with decorator-based tools and external MCP server integration**\n\nA Python framework that solves the complexity of claude-code-sdk tool integration through an intuitive decorator-based approach. Created to provide a stable, consistent development experience similar to Google's Agent Development Kit (ADK), this toolkit enables effortless creation of Claude Code agents with custom MCP tools and seamless integration with existing MCP servers.\n\n## Table of Contents\n\n- [Why Claude Agent Toolkit?](#why-claude-agent-toolkit)\n- [When Should You Use This?](#when-should-you-use-this)\n- [Quick Start](#quick-start)\n- [Installation & Setup](#installation--setup)\n- [Usage Examples](#usage-examples)\n- [Core Features](#core-features)\n- [Architecture](#architecture)\n- [Built-in Tools](#built-in-tools)\n- [Creating Custom Tools](#creating-custom-tools)\n- [FAQ](#faq)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why Claude Agent Toolkit?\n\n### The Problem\nWorking directly with claude-code-sdk presents two major challenges:\n1. **Complex Tool Integration** - Manual MCP server setup, connection handling, and tool registration\n2. **Inconsistent Execution** - Different local environments causing unpredictable behavior\n\n### The Solution\nClaude Agent Toolkit solves these issues through:\n- **\ud83c\udfaf Decorator-Based Tools** - Simple `@tool` decorator converts any Python function into a Claude-compatible tool\n- **\ud83d\udc33 Isolated Execution** - Docker containers ensure consistent behavior across all environments\n- **\u26a1 Zero Configuration** - Automatic MCP server management and tool discovery\n\n*\"An intuitive and stable development experience similar to Google's ADK\"* - [Cheolwan Park, Creator](https://blog.codingvillain.com/post/claude-agent-toolkit)\n\n### Before vs After\n\n**Before (Direct claude-code-sdk):**\n```python\n# Complex MCP server setup\n# Manual connection management\n# Environment-specific configurations\n# Inconsistent tool behavior\n```\n\n**After (Claude Agent Toolkit):**\n```python\nclass CalculatorTool(BaseTool):\n @tool(description=\"Adds two numbers together\")\n async def add(self, a: float, b: float) -> dict:\n return {\"result\": a + b}\n\nagent = Agent(tools=[CalculatorTool()])\n```\n\n## When Should You Use This?\n\n> **Update**: Recent updates to claude-code-sdk have simplified tool addition significantly. This has substantially reduced the necessity for Claude Agent Toolkit compared to when it was first created.\n\n### Use claude-code-sdk When:\n- Building simple agents with basic tooling needs\n- Rapid prototyping and experimentation\n- Utilizing local environment configurations\n- Working with subprocess execution only\n\n### Use Claude Agent Toolkit When:\n- **Isolated Execution Required** - Docker containers for production consistency\n- **CPU-Intensive Tools** - Parallel execution in separate process pools with `parallel=True`\n- **Production Environments** - Consistent execution across different deployments\n- **Complex Tool Orchestration** - Multiple tools with state management\n\n### Quick Comparison\n\n| Feature | claude-code-sdk | Claude Agent Toolkit |\n|---------|----------------|---------------------|\n| **Setup Complexity** | Simple (recent updates) | Minimal with decorators |\n| **Execution** | Same process | Docker/Subprocess isolation |\n| **CPU-Intensive Tasks** | Blocking | Parallel with `parallel=True` |\n| **Environment Consistency** | Variable | Guaranteed with Docker |\n| **Best For** | Prototyping, simple tools | Production, complex tools |\n\n## Quick Start\n\n```python\nfrom claude_agent_toolkit import Agent, BaseTool, tool\n\n# 1. Create a custom tool with @tool decorator\nclass CalculatorTool(BaseTool):\n @tool(description=\"Adds two numbers together\")\n async def add(self, a: float, b: float) -> dict:\n result = a + b\n return {\n \"operation\": f\"{a} + {b}\",\n \"result\": result,\n \"message\": f\"The result of adding {a} and {b} is {result}\"\n }\n\n# 2. Create and run an agent\nasync def main():\n agent = Agent(\n system_prompt=\"You are a helpful calculator assistant\",\n tools=[CalculatorTool()],\n model=\"sonnet\" # haiku, sonnet, or opus\n )\n\n result = await agent.run(\"What is 15 + 27?\")\n print(result) # Claude will use your tool and return the answer\n\nif __name__ == \"__main__\":\n import asyncio\n asyncio.run(main())\n```\n\n## Installation & Setup\n\n### Prerequisites\n\n- **Python 3.12+** with `uv` package manager\n- **Docker Desktop** (required for Docker executor, recommended)\n- **Claude Code OAuth Token** - Get from [Claude Code](https://claude.ai/code)\n\n### Install the Package\n\n```bash\n# Using pip\npip install claude-agent-toolkit\n\n# Using uv (recommended)\nuv add claude-agent-toolkit\n\n# Using poetry\npoetry add claude-agent-toolkit\n```\n\n### Set Your OAuth Token\n\nGet your token by running `claude setup-token` in your terminal, then:\n\n```bash\nexport CLAUDE_CODE_OAUTH_TOKEN='your-token-here'\n```\n\n### Quick Verification\n\n```bash\n# Clone examples (optional)\ngit clone https://github.com/cheolwanpark/claude-agent-toolkit.git\ncd claude-agent-toolkit/src/examples/calculator\npython main.py\n```\n\n## Usage Examples\n\n### Basic Agent with Custom Tool\n\n```python\nfrom claude_agent_toolkit import Agent, BaseTool, tool, ExecutorType\n\nclass MyTool(BaseTool):\n def __init__(self):\n super().__init__()\n self.counter = 0 # Explicit data management\n\n @tool(description=\"Increment counter and return value\")\n async def increment(self) -> dict:\n self.counter += 1\n return {\"value\": self.counter}\n\n# Docker executor (default, production-ready)\nagent = Agent(tools=[MyTool()])\n\n# Subprocess executor (faster startup, development)\nagent = Agent(tools=[MyTool()], executor=ExecutorType.SUBPROCESS)\n\nresult = await agent.run(\"Increment the counter twice\")\n```\n\n### Model Selection\n\n```python\n# Fast and efficient for simple tasks\nweather_agent = Agent(\n tools=[weather_tool],\n model=\"haiku\"\n)\n\n# Balanced performance (default)\ngeneral_agent = Agent(\n tools=[calc_tool, weather_tool],\n model=\"sonnet\"\n)\n\n# Most capable for complex reasoning\nanalysis_agent = Agent(\n tools=[analysis_tool],\n model=\"opus\"\n)\n\n# Override per query\nresult = await weather_agent.run(\n \"Complex weather pattern analysis\",\n model=\"opus\"\n)\n```\n\n### CPU-Intensive Operations\n\n```python\nclass HeavyComputeTool(BaseTool):\n @tool(description=\"Heavy computation\", parallel=True, timeout_s=120)\n def process_data(self, data: str) -> dict:\n # Sync function - runs in separate process\n import time\n time.sleep(5) # Simulate heavy work\n return {\"processed\": f\"result_{data}\"}\n```\n\n### Error Handling\n\n```python\nfrom claude_agent_toolkit import (\n Agent, BaseTool,\n ConfigurationError, ConnectionError, ExecutionError\n)\n\ntry:\n agent = Agent(tools=[MyTool()])\n result = await agent.run(\"Process my request\")\n\nexcept ConfigurationError as e:\n print(f\"Setup issue: {e}\") # Missing token, invalid config\n\nexcept ConnectionError as e:\n print(f\"Connection failed: {e}\") # Docker, network issues\n\nexcept ExecutionError as e:\n print(f\"Execution failed: {e}\") # Tool failures, timeouts\n```\n\n## Core Features\n\n- **\ud83c\udfaf Decorator-Based Tools** - Transform any Python function into a Claude tool with simple `@tool` decorator\n- **\ud83d\udd0c External MCP Integration** - Connect to existing MCP servers via stdio and HTTP transports\n- **\ud83d\udc33 Isolated Execution** - Docker containers ensure consistent behavior across all environments\n- **\u26a1 Zero Configuration** - Automatic MCP server management, port selection, and tool discovery\n- **\ud83d\udd27 Flexible Execution Modes** - Choose Docker isolation (production) or subprocess (development)\n- **\ud83d\udcdd Explicit Data Management** - You control data persistence with no hidden state\n- **\u2699\ufe0f CPU-bound Operations** - Process pools for heavy computations with parallel processing\n- **\ud83c\udfad Multi-tool Coordination** - Claude Code intelligently orchestrates multiple tools\n- **\ud83c\udfd7\ufe0f Production Ready** - Built for scalable, reliable agent deployment\n\n## Architecture\n\n### Execution Modes\n\n| Feature | Docker (Default) | Subprocess |\n|---------|------------------|------------|\n| **Isolation** | Full container isolation | Process isolation only |\n| **Setup Time** | ~3 seconds | ~0.5 seconds |\n| **Use Case** | Production, testing | Development, CI/CD |\n| **Requirements** | Docker Desktop | None |\n\n### Component Overview\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Your Tools \u2502 \u2502 Agent \u2502 \u2502 Claude Code \u2502\n\u2502 (MCP Servers) \u2502\u25c4\u2500\u2500\u25ba\u2502 (Orchestrator) \u2502\u25c4\u2500\u2500\u25ba\u2502 (Reasoning) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 \u2502 \u2502\n \u25bc \u25bc \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Host Process \u2502 \u2502 Docker Container \u2502 \u2502 Claude Code API \u2502\n\u2502 (localhost) \u2502 \u2502 or Subprocess \u2502 \u2502 (claude.ai) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## External MCP Server Integration\n\n### Connect to Existing MCP Servers\n\nIntegrate with any existing MCP server using stdio or HTTP transport:\n\n```python\nfrom claude_agent_toolkit import Agent\nfrom claude_agent_toolkit.tool.mcp import StdioMCPTool, HttpMCPTool\n\n# Connect to an MCP server via command execution\neverything_server = StdioMCPTool(\n command=\"npx\",\n args=[\"-y\", \"@modelcontextprotocol/server-everything\"],\n name=\"everything\"\n)\n\n# Connect to an HTTP MCP server\nhttp_server = HttpMCPTool(\n url=\"http://localhost:3001/mcp\",\n name=\"my-http-server\"\n)\n\n# Mix with your custom tools\nagent = Agent(\n system_prompt=\"You can use both custom and external tools\",\n tools=[MyCustomTool(), everything_server, http_server]\n)\n\nresult = await agent.run(\"Use the everything server to echo 'Hello World'\")\n```\n\n### When to Use External MCP Integration\n\n- **Existing MCP Ecosystem**: Leverage community MCP servers and tools\n- **Language Diversity**: Use MCP servers written in Node.js, Python, Go, etc.\n- **Specialized Tools**: Integrate domain-specific tools without reimplementation\n- **Rapid Prototyping**: Quickly test MCP servers before building custom equivalents\n- **Service Architecture**: Connect to MCP servers running as microservices\n\n### Supported Transports\n\n| Transport | Use Case | Example |\n|-----------|----------|---------|\n| **Stdio** | Command-line tools, npm packages | `npx` servers, Python scripts |\n| **HTTP** | Web services, microservices | REST APIs, containerized servers |\n\n## Built-in Tools\n\n### FileSystemTool - Secure File Operations\n\nControl exactly what files your agent can access with pattern-based permissions.\n\n```python\nfrom claude_agent_toolkit.tools import FileSystemTool\n\n# Define access patterns\npermissions = [\n (\"*.txt\", \"read\"), # Read all text files\n (\"data/**\", \"write\"), # Write to data directory\n (\"logs/*.log\", \"read\"), # Read log files only\n]\n\nfs_tool = FileSystemTool(\n permissions=permissions,\n root_dir=\"/path/to/workspace\" # Restrict to directory\n)\n\nagent = Agent(\n system_prompt=\"You are a file manager assistant\",\n tools=[fs_tool]\n)\n\nresult = await agent.run(\n \"List all text files and create a summary in data/report.txt\"\n)\n```\n\n### DataTransferTool - Type-Safe Data Transfer\n\nTransfer structured data between Claude agents and your application using Pydantic models.\n\n```python\nfrom claude_agent_toolkit.tools import DataTransferTool\nfrom pydantic import BaseModel, Field\nfrom typing import List\n\nclass UserProfile(BaseModel):\n name: str = Field(..., description=\"Full name\")\n age: int = Field(..., ge=0, le=150, description=\"Age in years\")\n interests: List[str] = Field(default_factory=list)\n\n# Create tool for specific model\nuser_tool = DataTransferTool.create(UserProfile, \"UserProfileTool\")\n\nagent = Agent(\n system_prompt=\"You handle user profile data transfers\",\n tools=[user_tool]\n)\n\n# Transfer data through Claude\nawait agent.run(\n \"Transfer user: Alice Johnson, age 28, interests programming and hiking\"\n)\n\n# Retrieve validated data\nuser_data = user_tool.get()\nif user_data:\n print(f\"Retrieved: {user_data.name}, age {user_data.age}\")\n```\n\n## Creating Custom Tools\n\n### Basic Tool Pattern\n\n```python\nfrom claude_agent_toolkit import BaseTool, tool\n\nclass MyTool(BaseTool):\n def __init__(self):\n super().__init__() # Server starts automatically\n self.data = {} # Explicit data management\n\n @tool(description=\"Async operation\")\n async def process_async(self, data: str) -> dict:\n # Async operations for I/O, API calls\n return {\"result\": f\"processed_{data}\"}\n\n @tool(description=\"CPU-intensive operation\", parallel=True, timeout_s=60)\n def process_heavy(self, data: str) -> dict:\n # Sync function - runs in separate process\n # Note: New instance created, self.data won't persist\n import time\n time.sleep(2)\n return {\"result\": f\"heavy_{data}\"}\n```\n\n### Context Manager Support\n\n```python\n# Single tool with guaranteed cleanup\nwith MyTool() as tool:\n agent = Agent(tools=[tool])\n result = await agent.run(\"Process my data\")\n# Server automatically cleaned up\n\n# Multiple tools\nwith MyTool() as calc_tool, WeatherTool() as weather_tool:\n agent = Agent(tools=[calc_tool, weather_tool])\n result = await agent.run(\"Calculate and check weather\")\n# Both tools cleaned up automatically\n```\n\n## FAQ\n\n### What is Claude Agent Toolkit?\n\nA Python framework that lets you build AI agents using Claude Code with custom tools. Unlike generic agent frameworks, this specifically leverages Claude Code's advanced reasoning capabilities with your existing subscription.\n\n### How is this different from other agent frameworks?\n\n- **Uses Claude Code**: Leverages Claude's production infrastructure and reasoning\n- **MCP Protocol**: Industry-standard tool integration, not proprietary APIs\n- **Explicit Data**: You control data persistence, no hidden state management\n- **Production Focus**: Built for real deployment, not just experiments\n\n### Do I need Docker?\n\nDocker is recommended for production but not required. Use `ExecutorType.SUBPROCESS` for development:\n\n```python\nagent = Agent(tools=[my_tool], executor=ExecutorType.SUBPROCESS)\n```\n\n### Which model should I use?\n\n- **haiku**: Fast, cost-effective for simple operations\n- **sonnet**: Balanced performance, good default choice\n- **opus**: Maximum capability for complex reasoning\n\n### How do I handle errors?\n\nThe framework provides specific exception types:\n\n```python\nfrom claude_agent_toolkit import ConfigurationError, ConnectionError, ExecutionError\n\ntry:\n result = await agent.run(\"task\")\nexcept ConfigurationError:\n # Missing OAuth token, invalid config\nexcept ConnectionError:\n # Docker/network issues\nexcept ExecutionError:\n # Tool failures, timeouts\n```\n\n### Can I use multiple tools together?\n\nYes! Claude Code intelligently orchestrates multiple tools:\n\n```python\nagent = Agent(tools=[calc_tool, weather_tool, file_tool])\nresult = await agent.run(\n \"Calculate the average temperature and save results to report.txt\"\n)\n```\n\n## Testing\n\nThe framework is validated through comprehensive examples rather than traditional unit tests. Each example demonstrates specific capabilities and serves as both documentation and validation.\n\n### Run Examples\n\n```bash\n# Clone the repository\ngit clone https://github.com/cheolwanpark/claude-agent-toolkit.git\ncd claude-agent-toolkit\n\n# Set your OAuth token\nexport CLAUDE_CODE_OAUTH_TOKEN='your-token-here'\n\n# Run different examples\ncd src/examples/calculator && python main.py # Stateful operations, parallel processing\ncd src/examples/weather && python main.py # External API integration\ncd src/examples/subprocess && python main.py # No Docker required\ncd src/examples/filesystem && python main.py # Permission-based file access\ncd src/examples/datatransfer && python main.py # Type-safe data transfer\ncd src/examples/mcp && python main.py # External MCP server integration\n```\n\n### Example Structure\n\n```\nsrc/examples/\n\u251c\u2500\u2500 calculator/ # Mathematical operations with state management\n\u251c\u2500\u2500 weather/ # External API integration (OpenWeatherMap)\n\u251c\u2500\u2500 subprocess/ # Subprocess executor demonstration\n\u251c\u2500\u2500 filesystem/ # FileSystemTool with permissions\n\u251c\u2500\u2500 datatransfer/ # DataTransferTool with Pydantic models\n\u251c\u2500\u2500 mcp/ # External MCP server integration (stdio, HTTP)\n\u2514\u2500\u2500 README.md # Detailed example documentation\n```\n\n### Docker Validation\n\nExamples can run with both executors:\n\n```bash\n# Docker executor (default)\npython main.py\n\n# Subprocess executor (faster startup)\n# Examples automatically use subprocess when Docker unavailable\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and validate with examples\n4. Run examples to verify functionality\n5. Submit a pull request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/cheolwanpark/claude-agent-toolkit.git\ncd claude-agent-toolkit\nuv sync --group dev\n\n# Validate your changes by running examples\nexport CLAUDE_CODE_OAUTH_TOKEN='your-token'\ncd src/examples/calculator && python main.py\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Created by**: [Cheolwan Park](https://github.com/cheolwanpark) \u2022 **Blog**: [Project Background](https://blog.codingvillain.com/post/claude-agent-toolkit)\n\n**Links**: [Homepage](https://github.com/cheolwanpark/claude-agent-toolkit) \u2022 [Claude Code](https://claude.ai/code) \u2022 [Issues](https://github.com/cheolwanpark/claude-agent-toolkit/issues) \u2022 [Model Context Protocol](https://modelcontextprotocol.io/)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python framework for building Claude Code agents with custom tools",
"version": "0.2.2",
"project_urls": {
"Changelog": "https://github.com/cheolwanpark/claude-agent-toolkit/blob/main/CHANGELOG.md",
"Claude Code": "https://claude.ai/code",
"Documentation": "https://github.com/cheolwanpark/claude-agent-toolkit#readme",
"Homepage": "https://github.com/cheolwanpark/claude-agent-toolkit",
"Issues": "https://github.com/cheolwanpark/claude-agent-toolkit/issues",
"Repository": "https://github.com/cheolwanpark/claude-agent-toolkit.git"
},
"split_keywords": [
"agent-framework",
" ai-agents",
" claude-agent-toolkit",
" claude-agents",
" claude-code",
" docker",
" mcp-tools",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "961f611c4ac7880cdb873e50fdef01bc8d086f57f45ccb1d77ed9e289455bc49",
"md5": "eb878eee1695147015c4f23b3b05bab1",
"sha256": "cc8dfc942ff5f563a0a0bdbf3aa77da1acd43b172f3d4f322b5c309835458ad7"
},
"downloads": -1,
"filename": "claude_agent_toolkit-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb878eee1695147015c4f23b3b05bab1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 41650,
"upload_time": "2025-09-13T14:10:55",
"upload_time_iso_8601": "2025-09-13T14:10:55.785795Z",
"url": "https://files.pythonhosted.org/packages/96/1f/611c4ac7880cdb873e50fdef01bc8d086f57f45ccb1d77ed9e289455bc49/claude_agent_toolkit-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7aa2fc75163e8247cc6be2c5977f77c39b3116fe18165bb3dd591c57cc83d8f2",
"md5": "b442f36df47fd195085ba4a501a483f0",
"sha256": "54098c26799dfe25f49f0f075fee397cd5ad048e911ebc334c457e7e6c24c8ba"
},
"downloads": -1,
"filename": "claude_agent_toolkit-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "b442f36df47fd195085ba4a501a483f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 62858,
"upload_time": "2025-09-13T14:10:57",
"upload_time_iso_8601": "2025-09-13T14:10:57.786905Z",
"url": "https://files.pythonhosted.org/packages/7a/a2/fc75163e8247cc6be2c5977f77c39b3116fe18165bb3dd591c57cc83d8f2/claude_agent_toolkit-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 14:10:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cheolwanpark",
"github_project": "claude-agent-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-agent-toolkit"
}
JSON
