Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<p align="center"> <img src="assets/banner.svg" alt="kwork-mcp" width="100%"> </p>
MCP server that exposes 25 tools for the Kwork freelance marketplace — browse projects, submit offers, manage orders, send messages, and more.
Built with FastMCP 3.x and pykwork.
Highlights
- Tool annotations — read-only, write, and destructive hints for safer agent interactions
- Input validation — all parameters validated before API calls
- Auto-relogin — automatic session refresh on 401 errors
- Error sanitization — internal details stay in logs, not in agent responses
- Rate limiting — built-in sliding window rate limiter
Setup
Requirements
- uv
- Kwork account (login/password or API token)
Install
When using uv no specific installation is needed. We will use uvx to directly run kwork-mcp.
Alternatively, install via pip:
pip install kwork-mcpOr from source:
git clone https://github.com/simonether/kwork-mcp.git
cd kwork-mcp
uv syncConfigure
| 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 | — | Proxy (HTTP / SOCKS4 / SOCKS5) |
KWORK_TIMEOUT | no | 30 | Request timeout in seconds |
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.
Proxy URL formats:
KWORK_PROXY_URL=http://proxy.example.com:8080
KWORK_PROXY_URL=socks5://proxy.example.com:1080
KWORK_PROXY_URL=socks5://user:[email protected]:1080Usage
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"kwork": {
"command": "uvx",
"args": ["kwork-mcp"],
"env": {
"KWORK_LOGIN": "your_login",
"KWORK_PASSWORD": "your_password"
}
}
}
}Claude Code
claude mcp add kwork -e KWORK_LOGIN=your_login -e KWORK_PASSWORD=your_password -- uvx kwork-mcpVS Code
Add to .vscode/mcp.json:
{
"mcp": {
"servers": {
"kwork": {
"command": "uvx",
"args": ["kwork-mcp"],
"env": {
"KWORK_LOGIN": "your_login",
"KWORK_PASSWORD": "your_password"
}
}
}
}
}stdio
uvx kwork-mcpTools
<details> <summary><strong>Profile</strong> (3 tools)</summary>
| Tool | Description |
|---|---|
get_me | Current user profile, rating, balance |
get_connects | Connect count for exchange offers |
get_user_info | Public user info by ID |
</details>
<details> <summary><strong>Projects</strong> (4 tools)</summary>
| 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 |
</details>
<details> <summary><strong>Offers</strong> (4 tools)</summary>
| 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 |
</details>
<details> <summary><strong>Orders</strong> (3 tools)</summary>
| 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 |
</details>
<details> <summary><strong>Dialogs</strong> (4 tools)</summary>
| Tool | Description |
|---|---|
list_dialogs | Conversations with latest messages |
get_dialog | Messages by username |
send_message | Send direct message |
mark_dialog_read | Mark as read |
</details>
<details> <summary><strong>Kworks</strong> (4 tools)</summary>
| 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 |
</details>
<details> <summary><strong>Categories</strong> (2 tools)</summary>
| Tool | Description |
|---|---|
list_categories | Full category tree |
get_favorite_categories | User's favorite categories |
</details>
<details> <summary><strong>Notifications</strong> (1 tool)</summary>
| Tool | Description |
|---|---|
list_notifications | User notifications |
</details>
Development
uv sync --dev
uv run python -m pytest tests/ -x -v --cov=kwork_mcp --cov-report=term-missing
uv run ruff check .
uv run ruff format --check .