NeedYourHands MCP Server

MCP (Model Context Protocol) server that allows AI agents to interact with the NeedYourHands.com marketplace -- searching for, booking and managing human workers for real-world tasks.

Prerequisites

• Python 3.11+
• A running NeedYourHands backend API (default: http://localhost:8000)
• A valid API key obtained from the platform

Installation

From PyPI (recommended)

uvx needyourhands-mcp
# or
pip install needyourhands-mcp

From source

cd mcp-server
pip install -e .

Using uv (from source)

cd mcp-server
uv pip install -e .

Configuration

The server reads two environment variables:

Variable	Default	Description
NEEDYOURHANDS_API_URL	http://localhost:8000	Base URL of the backend API (https://api.needyourhands.com in production)
NEEDYOURHANDS_API_KEY	(empty)	API key for agent authentication

API Endpoints

The MCP server communicates with the backend at:

• List tools: GET {API_URL}/api/v1/mcp/tools/list
• Call tool: POST {API_URL}/api/v1/mcp/tools/call

In production: https://api.needyourhands.com/api/v1/mcp/tools/call

Running

# Direct
needyourhands-mcp

# Or via Python
python -m needyourhands_mcp.server

Claude Desktop Configuration

Add the following to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "needyourhands": {
      "command": "needyourhands-mcp",
      "env": {
        "NEEDYOURHANDS_API_URL": "https://api.needyourhands.com",
        "NEEDYOURHANDS_API_KEY": "nyh_VOTRE_CLE"
      }
    }
  }
}

Or if running from source with uv:

{
  "mcpServers": {
    "needyourhands": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server", "needyourhands-mcp"],
      "env": {
        "NEEDYOURHANDS_API_URL": "https://api.needyourhands.com",
        "NEEDYOURHANDS_API_KEY": "nyh_VOTRE_CLE"
      }
    }
  }
}

Available Tools

search_humans

Search for available human workers filtered by skills, location, budget and urgency.

Parameters:

Name	Type	Required	Default	Description
skills	string[]	Yes	-	Skills to search for
location	string	Yes	-	City or address to search around
radius_km	integer	No	25	Search radius in km (1-500)
budget_max_eur	number	No	100.0	Max budget in EUR
urgency	string	No	"normal"	"normal" or "urgent"

Returns: List of matching workers with ratings, skills, city and availability.

book_human

Book a specific worker for a task. Creates a mission and sets up escrow payment.

Parameters:

Name	Type	Required	Description
human_id	string	Yes	ID of the worker to book
task_title	string	Yes	Title of the task
task_description	string	Yes	Detailed task description
location	string	Yes	Where the task is performed
deadline	string	Yes	ISO 8601 deadline
budget_eur	number	Yes	Budget in EUR

Returns: Mission ID, status, estimated start time and worker name.

get_availability

Check a worker's availability for a specific date.

Parameters:

Name	Type	Required	Description
human_id	string	Yes	ID of the worker
date	string	Yes	ISO date (YYYY-MM-DD)
time_range	string	No	Time range like "09:00-18:00"

Returns: Whether the worker is available, time slots, and next available date.

submit_task

Submit a task to the marketplace without pre-selecting a worker. The platform matches it with the best available candidates.

Parameters:

Name	Type	Required	Description
title	string	Yes	Title of the task
description	string	Yes	Detailed description
required_skills	string[]	Yes	Skills needed
location	string	Yes	Where the task is performed
budget_eur	number	Yes	Budget in EUR
deadline	string	Yes	ISO 8601 deadline

Returns: Task ID, number of matching workers, and status.

get_task_status

Get the current status of a mission including proofs, timeline and ETA.

Parameters:

Name	Type	Required	Description
mission_id	string	Yes	ID of the mission

Returns: Status, proofs, worker name, ETA and full event timeline.

verify_proof

Approve or reject a proof submitted by a worker. When all proofs are approved, the mission is automatically completed and payment captured.

Parameters:

Name	Type	Required	Description
mission_id	string	Yes	ID of the mission
proof_index	integer	Yes	Index of the proof (0 = first)
approved	boolean	Yes	true = approve, false = reject
rejection_reason	string	No	Rejection reason (required if rejected)

Returns: Verification status, new mission status, and payment capture result.

cancel_mission

Cancel a mission with a reason. Payment is automatically refunded (if captured) or authorization cancelled (if escrowed). Completed or already cancelled missions cannot be cancelled.

Parameters:

Name	Type	Required	Description
mission_id	string	Yes	ID of the mission
reason	string	Yes	Cancellation reason

Returns: New status, payment action taken, and cancellation timestamp.

send_message

Send a message in the mission chat. The message appears in real-time on the worker's dashboard.

Parameters:

Name	Type	Required	Description
mission_id	string	Yes	ID of the mission
message	string	Yes	Message content (max 5000 chars)

Returns: Message ID, sender type, sender name and timestamp.

rate_human

Rate a worker after a completed mission.

Parameters:

Name	Type	Required	Description
mission_id	string	Yes	ID of the completed mission
rating	integer	Yes	Rating 1-5
comment	string	No	Optional feedback

Returns: Success status and the worker's new average rating.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

License

Proprietary - NeedYourHands.com