mcp-server-mturk 0.1.0

MCP server for Amazon Mechanical Turk - enables AI agents to create HITs, review assignments, manage workers, and access human intelligence

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:

uvx mcp-server-mturk

Using pip

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
2. Create a new user with AmazonMechanicalTurkFullAccess policy
3. Generate access keys for the user

MTurk Account Setup

1. Create an MTurk Requester account
2. For testing, also register for the MTurk Sandbox

Usage with AI Clients

Claude Code

# 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:

{
  "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:

{
  "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:

{
  "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

# 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

npx @modelcontextprotocol/inspector uvx mcp-server-mturk

Building

uv build

Publishing to PyPI

uv publish

License

MIT

Links

• Model Context Protocol
• MTurk API Documentation
• MTurk Requester Portal
• MTurk Sandbox