# mcp-server-mturk

An MCP (Model Context Protocol) server that enables AI agents to interact with Amazon Mechanical Turk. This allows AI systems to request human intelligence for surveys, data labeling, content moderation, and any other MTurk-supported task.

## Features

- **24 tools** covering the full MTurk API
- **HIT Management**: Create, list, update, and delete Human Intelligence Tasks
- **Assignment Workflow**: Review, approve, reject, and bulk-approve worker submissions
- **Qualification System**: Create custom qualifications to filter workers
- **Worker Management**: Block/unblock workers, send notifications, pay bonuses
- **Account Management**: Check balance, list reviewable HITs

## Installation

### Using uvx (recommended)

No installation needed. Run directly:

```bash
uvx mcp-server-mturk
```

### Using pip

```bash
pip install mcp-server-mturk
python -m mturk_mcp.server
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `AWS_ACCESS_KEY_ID` | Yes | Your AWS access key with MTurk permissions |
| `AWS_SECRET_ACCESS_KEY` | Yes | Your AWS secret key |
| `MTURK_SANDBOX` | No | Set to `true` for sandbox mode (testing) |

### AWS Credentials Setup

1. Go to [AWS IAM Console](https://console.aws.amazon.com/iam/)
2. Create a new user with `AmazonMechanicalTurkFullAccess` policy
3. Generate access keys for the user

### MTurk Account Setup

1. Create an [MTurk Requester account](https://requester.mturk.com/)
2. For testing, also register for the [MTurk Sandbox](https://requestersandbox.mturk.com/)

## Usage with AI Clients

### Claude Code

```bash
# Sandbox mode (recommended for testing)
claude mcp add mturk-sandbox \
  --env AWS_ACCESS_KEY_ID=your_key \
  --env AWS_SECRET_ACCESS_KEY=your_secret \
  --env MTURK_SANDBOX=true \
  -- uvx mcp-server-mturk

# Production mode (uses real money!)
claude mcp add mturk \
  --env AWS_ACCESS_KEY_ID=your_key \
  --env AWS_SECRET_ACCESS_KEY=your_secret \
  -- uvx mcp-server-mturk
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mturk-sandbox": {
      "command": "uvx",
      "args": ["mcp-server-mturk"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret",
        "MTURK_SANDBOX": "true"
      }
    }
  }
}
```

Config file locations:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Cursor

Add to Cursor's MCP settings:

```json
{
  "mcpServers": {
    "mturk": {
      "command": "uvx",
      "args": ["mcp-server-mturk"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret",
        "MTURK_SANDBOX": "true"
      }
    }
  }
}
```

### Using pip instead of uvx

Replace `"command": "uvx", "args": ["mcp-server-mturk"]` with:

```json
{
  "command": "python",
  "args": ["-m", "mturk_mcp.server"]
}
```

## Available Tools

### HIT Operations (6 tools)

| Tool | Description |
|------|-------------|
| `create_hit` | Create a new Human Intelligence Task with HTML form |
| `get_hit` | Get details and status of a specific HIT |
| `list_hits` | List all HITs for your account |
| `delete_hit` | Delete a HIT (must have no pending assignments) |
| `update_hit_expiration` | Extend or expire a HIT |
| `create_additional_assignments` | Add more worker slots to an existing HIT |

### Assignment Management (5 tools)

| Tool | Description |
|------|-------------|
| `list_assignments` | Get all worker submissions for a HIT |
| `get_assignment` | Get details including worker's answer |
| `approve_assignment` | Approve and pay for completed work |
| `reject_assignment` | Reject unsatisfactory work (use sparingly) |
| `approve_all_submitted_assignments` | Bulk approve all pending assignments |

### Qualification Management (5 tools)

| Tool | Description |
|------|-------------|
| `create_qualification_type` | Create a custom worker qualification |
| `list_qualification_types` | List available qualifications |
| `assign_qualification` | Grant a qualification to a worker |
| `revoke_qualification` | Remove a qualification from a worker |
| `get_qualification_score` | Check a worker's qualification value |

### Worker Management (6 tools)

| Tool | Description |
|------|-------------|
| `block_worker` | Block a worker from all your HITs |
| `unblock_worker` | Remove a worker block |
| `list_blocked_workers` | List all blocked workers |
| `notify_workers` | Send email to workers |
| `send_bonus` | Send bonus payment to a worker |
| `list_bonus_payments` | List bonus payments made |

### Account & Utility (2 tools)

| Tool | Description |
|------|-------------|
| `get_account_balance` | Check your MTurk account balance |
| `list_reviewable_hits` | Find HITs with work ready for review |

## Example Prompts

Once connected, you can ask your AI assistant things like:

```
"Check my MTurk account balance"

"Create a survey HIT asking 100 people their favorite programming language, paying $0.10 each"

"List all my HITs and show which ones have pending assignments"

"Show me the submitted assignments for HIT abc123"

"Approve all submitted assignments for HIT abc123 with the message 'Thank you!'"

"Send a $0.50 bonus to worker xyz789 for their detailed response"

"Create a 'Trusted Worker' qualification and assign it to workers who did good work"
```

## Sandbox vs Production

| Mode | Environment Variable | Use For |
|------|---------------------|---------|
| **Sandbox** | `MTURK_SANDBOX=true` | Testing, development, no real money |
| **Production** | `MTURK_SANDBOX=false` (or unset) | Real HITs, real workers, real payments |

**Always test with sandbox first!** Production mode uses real money and interacts with real workers.

## Development

### Running locally

```bash
# Clone and install
git clone https://github.com/davidmcsharry/mcp-server-mturk
cd mcp-server-mturk
uv sync

# Run the server
uv run python -m mturk_mcp.server
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector uvx mcp-server-mturk
```

### Building

```bash
uv build
```

### Publishing to PyPI

```bash
uv publish
```

## License

MIT

## Links

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MTurk API Documentation](https://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/Welcome.html)
- [MTurk Requester Portal](https://requester.mturk.com/)
- [MTurk Sandbox](https://requestersandbox.mturk.com/)
