kwork-mcp 0.1.0

MCP server for managing Kwork freelance marketplace

MCP server that exposes 25 tools for the Kwork freelance marketplace — browse projects, submit offers, manage orders, send messages, and more.

Built with FastMCP (via MCP Python SDK) and pykwork.

🚀 Setup

Requirements

• Python 3.12+
• uv
• Kwork account (login/password or API token)

Install

git clone https://github.com/simonether/kwork-mcp.git
cd kwork-mcp
uv sync

Configure

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Variable	Required	Default	Description
KWORK_LOGIN	yes*	—	Kwork login
KWORK_PASSWORD	yes*	—	Kwork password
KWORK_TOKEN	yes*	—	Auth token (skips login)
KWORK_PHONE_LAST	no	—	Last 4 digits of phone (2FA)
KWORK_PROXY_URL	no	—	SOCKS5 proxy
KWORK_RPS_LIMIT	no	2	Requests per second
KWORK_BURST_LIMIT	no	5	Burst limit
KWORK_TOKEN_FILE	no	~/.kwork_token	Token persistence path

*Either KWORK_TOKEN or both KWORK_LOGIN + KWORK_PASSWORD.

Auth priority: KWORK_TOKEN env → saved token file → fresh login.

💡 Usage

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kwork": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/kwork-mcp", "kwork-mcp"],
      "env": {
        "KWORK_LOGIN": "your_login",
        "KWORK_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code

claude mcp add kwork -- uv run --directory /path/to/kwork-mcp kwork-mcp

stdio

uv run kwork-mcp

🛠 Tools

Profile (3 tools)

Tool	Description
get_me	Current user profile, rating, balance
get_connects	Connect count for exchange offers
get_user_info	Public user info by ID

Projects (4 tools)

Tool	Description
list_projects	Browse exchange projects with filters
get_project	Project details by ID
search_projects	Search by text query
get_exchange_info	Exchange marketplace stats

Offers (4 tools)

Tool	Description
list_my_offers	Your exchange offers
get_offer	Offer details by ID
submit_offer	Submit offer to a project (costs 1 connect)
delete_offer	Delete an offer

Orders (3 tools)

Tool	Description
list_worker_orders	Seller orders (all statuses)
get_order_details	Order details by ID
send_order_for_approval	Submit work for buyer review

Dialogs (4 tools)

Tool	Description
list_dialogs	Conversations with latest messages
get_dialog	Messages by username
send_message	Send direct message
mark_dialog_read	Mark as read

Kworks (4 tools)

Tool	Description
list_my_kworks	Your services grouped by status
get_kwork_details	Kwork details by ID
start_kwork	Activate a paused kwork
pause_kwork	Pause an active kwork

Categories (2 tools)

Tool	Description
list_categories	Full category tree
get_favorite_categories	User's favorite categories

Notifications (1 tool)

Tool	Description
list_notifications	User notifications

🧑‍💻 Development

uv sync --dev
uv run python -m pytest tests/ -x -v
uv run ruff check .
uv run ruff format --check .

License

MIT