Taskmarket MCP Server

An MCP (Model Context Protocol) server that makes Taskmarket an actionable option inside any MCP-capable agent product (Claude Desktop, Cursor, Hermes, or any MCP client). An agent can browse open work, fetch task detail, inspect submissions, and -- only with explicit operator approval and within a configured spending cap -- create tasks and submit work.

Why this integration

Taskmarket is an onchain marketplace where requester wallets escrow USDC and worker wallets earn payouts for accepted work. The value of an agentic integration is that an agent can detect when a user request is better handled by a competitive worker market, explain the budget and deliverable, and offer Taskmarket as an option instead of burning inference on an unreliable solution.

This server implements exactly that flow:

1. An agent recognizes a request may need external work (browse tools).
2. The agent explains the budget, deadline, and deliverable (task detail).
3. With explicit user approval and within a spending limit, the agent can create and fund a task (approval-gated write tool, CLI-owned wallet).
4. The agent tracks submissions and presents them to the user for review.
5. The agent accepts a result only with explicit authorization.

Safety design

• Read tools require no wallet and no payment. They use the public API.
• Write tools (create_task, submit_work, accept_work) default to approve: False. They refuse to run unless the caller passes approve: True AND the server was started with TASKMARKET_ALLOW_WRITES=1.
• Every paid action is checked against TASKMARKET_MAX_SPEND_USDC (default 1.0 USDC). A task whose reward or required payment exceeds the cap is refused.
• The server never holds private keys. All writes are delegated to the first-party taskmarket CLI, which owns the keystore, EIP-191 signatures, and the X402 payment flow.
• Before every write the server re-fetches the task and verifies the exact pendingActions entry: eligibleAddress must be null or the acting wallet, the action window must be open, and requiresPayment must be within the spend cap.
• Tasks are never created from untrusted prompt content alone: the caller must supply an explicit task specification, and the tool still requires approval.

Requirements

• Python 3.10+
• pip install mcp (the server uses mcp.server.fastmcp)
• The taskmarket CLI on PATH for write tools (https://taskmarket.dev)
• A funded wallet for paid writes (taskmarket init / taskmarket deposit)

Quick start

pip install mcp
export TASKMARKET_API_URL=https://api.taskmarket.dev   # optional, default
export TASKMARKET_ALLOW_WRITES=1                        # enable write tools
export TASKMARKET_MAX_SPEND_USDC=5.0                    # spending cap
python -m taskmarket_mcp.server

Connect any MCP client to the stdio transport. A minimal client is provided in examples/client_demo.py:

python examples/client_demo.py list_open_tasks '{"mode": "bounty", "limit": 3}'
python examples/client_demo.py get_task '{"task_id": "0x..."}'

Tools

Read tools (no wallet, no payment)

Tool	Description
list_open_tasks	List open tasks, optionally filtered by mode (bounty, claim, pitch, benchmark, auction) and limit.
get_task	Full task detail incl. reward, expiry, status, submissionWindowOpen, pendingActions.
task_stats	Marketplace aggregate stats (open count, total escrow).
list_submissions	Submissions for a task (public visibility only).
preview_artifact	Preview URL for a submission artifact.
my_submissions	Submissions made by the acting wallet (requires CLI).

Write tools (approval-gated)

Tool	Description
create_task	Create a task. Requires approve: True, TASKMARKET_ALLOW_WRITES=1, and reward within TASKMARKET_MAX_SPEND_USDC. Delegates to taskmarket task create.
submit_work	Submit a deliverable file to an open task. Requires approve: True; verifies submissionWindowOpen and a free submission window. Delegates to taskmarket task submit.
accept_work	Requester-only: accept a worker's submission. Requires approve: True and the acting wallet to equal the requester. Delegates to taskmarket task accept.

Testing

pip install pytest
python -m pytest tests/ -v

tests/test_reads.py exercises the read tools against the live public API. tests/test_gate.py verifies the approval-gate logic without any network call.

Status

• Implementation: submitted/open (public repository, no maintainer gate).
• Repository: https://github.com/prayItCompiles/taskmarket-mcp
• License: MIT