# claude-agent-mcp

An MCP (Model Context Protocol) server that wraps the [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk). It uses Claude Code's built-in OAuth authentication, so **no API key is required** — just `claude login` and you're ready to go.

## Features

| Tool | Description |
|------|-------------|
| `claude_query` | General-purpose queries — uses Claude's reasoning without any tools |
| `claude_code_task` | Coding tasks with file system access (read/write/edit/search) |
| `claude_web_search` | Web search with result summarization |
| `claude_multi_turn` | Fully customizable agent execution — configure tools, permissions, budget, and more |

## Prerequisites

- [Bun](https://bun.sh/) v1.0+
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and logged in (`claude login`)

## Installation

```bash
git clone https://github.com/j-token/claude-agent-mcp.git
cd claude-agent-mcp
bun install
```

## Usage

### Run directly

```bash
bun start
```

### Add to Claude Code as an MCP server

Add the following to your Claude Code MCP settings (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "claude-agent": {
      "command": "bun",
      "args": ["run", "/path/to/claude-agent-mcp/src/index.ts"]
    }
  }
}
```

### Add to Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "claude-agent": {
      "command": "bun",
      "args": ["run", "/path/to/claude-agent-mcp/src/index.ts"]
    }
  }
}
```

## Tools

### `claude_query`

Send a prompt to Claude without any tools. Best for reasoning, text generation, and Q&A.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | The prompt to send |
| `systemPrompt` | string | No | System prompt |
| `model` | string | No | Model to use (e.g., `claude-sonnet-4-6`) |
| `maxTurns` | number | No | Max conversation turns (default: 3) |

### `claude_code_task`

Perform coding tasks with file system access. Can read, write, edit, and search files.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Description of the coding task |
| `cwd` | string | No | Working directory (absolute path) |
| `permissionMode` | string | No | `plan` (default), `acceptEdits`, or `bypassPermissions` |
| `allowedTools` | string[] | No | Tools to allow (default: Read, Edit, Write, Glob, Grep, Bash) |
| `model` | string | No | Model to use |
| `maxTurns` | number | No | Max turns (default: 10) |

### `claude_web_search`

Search the web and get a summarized result.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `searchQuery` | string | Yes | What to search for |
| `model` | string | No | Model to use |
| `maxTurns` | number | No | Max turns (default: 5) |

### `claude_multi_turn`

Fully customizable agent execution. Configure every aspect of the agent run.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | The prompt |
| `systemPrompt` | string | No | System prompt |
| `allowedTools` | string[] | No | Tools to allow |
| `permissionMode` | string | No | `default`, `acceptEdits`, `plan`, or `bypassPermissions` |
| `cwd` | string | No | Working directory |
| `model` | string | No | Model to use |
| `maxTurns` | number | No | Max conversation turns |
| `maxBudgetUsd` | number | No | Max budget in USD |

## How It Works

```
┌─────────────┐     stdio      ┌───────────────────┐     OAuth     ┌─────────────┐
│  MCP Client │ ◄────────────► │ claude-agent-mcp  │ ◄───────────► │  Claude API  │
│ (Claude Code │                │  (this server)    │               │             │
│  / Desktop)  │                └───────────────────┘               └─────────────┘
└─────────────┘
```

1. An MCP client (Claude Code, Claude Desktop, etc.) connects to this server via stdio.
2. The client calls one of the registered tools (`claude_query`, `claude_code_task`, etc.).
3. This server delegates the request to the Claude Agent SDK, which uses your existing OAuth session.
4. The response is streamed back and returned to the client.

## Development

```bash
# Type-check
bun run typecheck

# Build
bun run build
```

## License

[MIT](LICENSE)