English Français العربية

Kwork

Registre officiel E-commerce

Account-bound, typed and durable stdio MCP gateway for the Kwork freelance marketplace

Code source Site web Documentation

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

PYPI package kwork-mcp
Claude Code 
claude mcp add kwork -e 'KWORK_EXPECTED_USER_ID=<KWORK_EXPECTED_USER_ID>' -e 'KWORK_EXPECTED_USERNAME=<KWORK_EXPECTED_USERNAME>' -e 'KWORK_WRITES=confirm' -e 'KWORK_SITE=ru' -e 'KWORK_TIMEOUT=30' -e 'KWORK_STATE_DIR=<KWORK_STATE_DIR>' -e 'KWORK_PERSIST_TOKEN=true' -e 'KWORK_RPS_LIMIT=2' -e 'KWORK_BURST_LIMIT=4' -e 'KWORK_ROUTE_RPS_LIMIT=1' -e 'KWORK_ROUTE_BURST_LIMIT=2' -e 'KWORK_RATE_WAIT_TIMEOUT=20' -e 'KWORK_AUTH_LOCK_TIMEOUT=90' -e 'KWORK_READ_ATTEMPTS=3' -e 'KWORK_RETRY_BACKOFF_BASE=0.5' -e 'KWORK_RETRY_BACKOFF_MAX=8' -e 'KWORK_CIRCUIT_FAILURE_THRESHOLD=3' -e 'KWORK_CIRCUIT_OPEN_SECONDS=30' -e 'KWORK_PREPARATION_TTL_SECONDS=600' -e 'KWORK_WRITE_LEASE_SECONDS=120' -e 'KWORK_RECONCILIATION_MIN_AGE_SECONDS=15' -e 'KWORK_RECONCILIATION_ABSENCE_CONFIRMATIONS=2' -e 'KWORK_RECONCILIATION_ABSENCE_INTERVAL_SECONDS=15' -e 'KWORK_STATE_RETENTION_DAYS=30' -e 'KWORK_LOG_LEVEL=INFO' -- uvx kwork-mcp==1.5.2
Configuration JSON (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "kwork": {
            "command": "uvx",
            "args": [
                "kwork-mcp==1.5.2"
            ],
            "env": {
                "KWORK_EXPECTED_USER_ID": "<KWORK_EXPECTED_USER_ID>",
                "KWORK_EXPECTED_USERNAME": "<KWORK_EXPECTED_USERNAME>",
                "KWORK_WRITES": "confirm",
                "KWORK_SITE": "ru",
                "KWORK_TIMEOUT": "30",
                "KWORK_STATE_DIR": "<KWORK_STATE_DIR>",
                "KWORK_PERSIST_TOKEN": "true",
                "KWORK_RPS_LIMIT": "2",
                "KWORK_BURST_LIMIT": "4",
                "KWORK_ROUTE_RPS_LIMIT": "1",
                "KWORK_ROUTE_BURST_LIMIT": "2",
                "KWORK_RATE_WAIT_TIMEOUT": "20",
                "KWORK_AUTH_LOCK_TIMEOUT": "90",
                "KWORK_READ_ATTEMPTS": "3",
                "KWORK_RETRY_BACKOFF_BASE": "0.5",
                "KWORK_RETRY_BACKOFF_MAX": "8",
                "KWORK_CIRCUIT_FAILURE_THRESHOLD": "3",
                "KWORK_CIRCUIT_OPEN_SECONDS": "30",
                "KWORK_PREPARATION_TTL_SECONDS": "600",
                "KWORK_WRITE_LEASE_SECONDS": "120",
                "KWORK_RECONCILIATION_MIN_AGE_SECONDS": "15",
                "KWORK_RECONCILIATION_ABSENCE_CONFIRMATIONS": "2",
                "KWORK_RECONCILIATION_ABSENCE_INTERVAL_SECONDS": "15",
                "KWORK_STATE_RETENTION_DAYS": "30",
                "KWORK_LOG_LEVEL": "INFO"
            }
        }
    }
}

Variables d'environnement

  • KWORK_EXPECTED_USER_ID Kwork user ID to serve; optional when kwork-mcp login bound a single account, required when several are bound
  • KWORK_EXPECTED_USERNAME Optional second account identity check
  • KWORK_WRITES Sending to Kwork: confirm asks the user before each send (client dialog or chat), auto lets the agent send, off is read-only
  • KWORK_SITE Kwork site: ru (kwork.ru) or com (kwork.com); kwork.com has no project exchange
  • KWORK_TIMEOUT Kwork request timeout in seconds (1-120)
  • KWORK_STATE_DIR Absolute private directory shared by gateway processes for the same account
  • KWORK_PERSIST_TOKEN Use the verified account-scoped credential store; required for normal server startup
  • KWORK_RPS_LIMIT Shared account-level token refill rate
  • KWORK_BURST_LIMIT Shared account-level token bucket capacity
  • KWORK_ROUTE_RPS_LIMIT Shared per-route token refill rate
  • KWORK_ROUTE_BURST_LIMIT Shared per-route token bucket capacity
  • KWORK_RATE_WAIT_TIMEOUT Maximum seconds to wait for shared rate-limit admission
  • KWORK_AUTH_LOCK_TIMEOUT Maximum seconds to wait for account credential-store authentication coordination
  • KWORK_READ_ATTEMPTS Maximum attempts for retry-safe read requests only
  • KWORK_RETRY_BACKOFF_BASE Initial retry backoff for retry-safe reads, in seconds
  • KWORK_RETRY_BACKOFF_MAX Maximum retry backoff for retry-safe reads, in seconds
  • KWORK_CIRCUIT_FAILURE_THRESHOLD Shared route failures before opening the circuit
  • KWORK_CIRCUIT_OPEN_SECONDS Base shared circuit-open interval in seconds
  • KWORK_PREPARATION_TTL_SECONDS Safe write preparation lifetime
  • KWORK_WRITE_LEASE_SECONDS Durable one-writer lease duration in seconds
  • KWORK_RECONCILIATION_MIN_AGE_SECONDS Minimum age before ambiguous-write read-back (1-300 seconds)
  • KWORK_RECONCILIATION_ABSENCE_CONFIRMATIONS Complete absent observations required before a terminal result
  • KWORK_RECONCILIATION_ABSENCE_INTERVAL_SECONDS Minimum interval between absent observations (1-300 seconds)
  • KWORK_STATE_RETENTION_DAYS Retention for terminal durable write records
  • KWORK_LOG_LEVEL Gateway stderr log level: DEBUG, INFO, WARNING or ERROR

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. Что можно попросить у агента
  2. Быстрый старт
  3. Отправка откликов и сообщений
  4. kwork.com
  5. Если что-то не работает
  6. Инструменты
  7. Безопасность
  8. Разработка
  9. Лицензия

kwork-mcp подключает ваш аккаунт Kwork к ИИ-агенту: Claude Code, Claude Desktop, Codex, Cursor и другим MCP-клиентам. Агент ищет проекты на бирже, читает диалоги, заказы и офферы, готовит отклики. По умолчанию агент отправляет что-то на Kwork только после вашего «да» на точный текст.

Сайт проекта: simonether.github.io/kwork-mcp.

Что можно попросить у агента

  • «Найди свежие проекты про Telegram-ботов с бюджетом от 20 000 ₽ и скажи, какие мне подходят».
  • «Покажи диалоги с непрочитанными сообщениями и предложи ответы».
  • «Что с моими заказами? Где что-то ждёт моих действий?»
  • «Сколько у меня коннектов и какие мои отклики ещё висят?»
  • «Подготовь отклик на проект 3257238: 15 000 ₽, 5 дней» — агент покажет точный текст и цену и отправит только после вашего «да».

Быстрый старт

Нужны macOS или Linux, Python 3.12–3.14 и uv. Windows не поддерживается.

1. Войдите в Kwork (один раз)

В обычном терминале:

uvx kwork-mcp@1.5.2 login

Команда скрыто спросит логин и пароль Kwork, а также, по желанию, последние 4 цифры телефона и прокси, и покажет найденный аккаунт:

Найден аккаунт Kwork: your_name (user_id=123456). Привязать его? [y/N]: да

После подтверждения токен сохраняется в защищённое хранилище на вашем компьютере (~/.local/state/kwork-mcp). Логин и пароль нигде не сохраняются. В конце команда напечатает готовые команды подключения для Claude Code и Codex и блок для Claude Desktop и Cursor.

2. Подключите агента

Claude Code:

claude mcp add kwork --scope user -- uvx kwork-mcp@1.5.2

Codex:

codex mcp add kwork -- uvx kwork-mcp@1.5.2

Cursor:

Claude Desktop и другие клиенты

Claude Desktop: Settings → Developer → Edit Config, файл claude_desktop_config.json. Cursor без кнопки: ~/.cursor/mcp.json или .cursor/mcp.json проекта.

{
  "mcpServers": {
    "kwork": {
      "command": "uvx",
      "args": ["kwork-mcp@1.5.2"]
    }
  }
}

Claude Desktop не видит uvx из терминала, поэтому возьмите блок из вывода login: в нём уже указан полный путь к uvx.

Сервер сам найдёт аккаунт, с которым вы вошли. Если вы входили в несколько аккаунтов, укажите нужный: -e KWORK_EXPECTED_USER_ID=123456 или блок "env" в JSON.

Логин, пароль, токен и прокси в конфиг клиента не добавляйте: сервер с ними откажется запускаться.

3. Проверьте

Перезапустите клиент и попросите агента: «проверь статус аккаунта Kwork». Он вызовет account_status и покажет ваш user_id и имя.

Без клиента то же видно в терминале: uvx kwork-mcp@1.5.2 status покажет, с каким аккаунтом и сайтом запустится сервер, не обращаясь к Kwork. Сменить аккаунт: uvx kwork-mcp@1.5.2 logout, затем снова login.

Отправка откликов и сообщений

Отправку на Kwork (отклики, сообщения, удаление офферов, сдача заказа, запуск и пауза кворков) задаёт переменная KWORK_WRITES:

KWORK_WRITESЧто происходит
confirm (по умолчанию)Перед каждой отправкой агент показывает точный текст, цену и получателя и ждёт вашего «да»
autoАгент отправляет сам, когда это нужно для вашей задачи, без отдельного подтверждения
offТолько чтение: инструменты отправки скрыты, агент их не видит

В режиме confirm сервер в ответе prepare_write и в своих инструкциях указывает агенту показать вам запрос и отправлять только после вашего «да». Сам проверить это «да» сервер не может. Вторую кнопку даёт клиент: Claude Code и Claude Desktop по умолчанию спрашивают разрешение перед инструментом отправки, а в Codex то же включает default_tools_approval_mode = "writes" в настройках сервера [mcp_servers.kwork].

Режим выбирается в конфиге клиента, например для Claude Code:

claude mcp remove kwork --scope user
claude mcp add kwork --scope user -e KWORK_WRITES=auto -- uvx kwork-mcp@1.5.2

В режиме auto от чужих команд в текстах проектов и сообщений защищает только поведение агента: сервер помечает эти тексты как внешние данные, но проверить, что агент их не послушал, не может.

Каждая отправка идёт в два шага: сначала агент готовит точный запрос, затем выполняет его. Сервер помнит каждую запись и никогда не повторяет её сам.

Если связь оборвалась в момент отправки, результат становится «неизвестным», и агент сверяет его с Kwork, прежде чем делать что-то ещё. Пока такая запись не сверена, новые отправки для аккаунта заблокированы, чтобы не создать дубль.

kwork.com

По умолчанию сервер работает с kwork.ru. Для kwork.com добавьте в конфиг клиента KWORK_SITE=com. Например, для Claude Code вторым сервером рядом с kwork.ru:

claude mcp add kwork-com --scope user -e KWORK_SITE=com -- uvx kwork-mcp@1.5.2

Аккаунт и токен у kwork.ru и kwork.com общие, поэтому заново входить не нужно. Биржи проектов на kwork.com нет: поиск проектов, избранные категории и отклик на проект там отвечают site_unsupported. Диалоги, заказы и кворки работают как обычно, но заказы у каждого сайта свои. Запись, подготовленную для одного сайта, отправляет и сверяет только сервер того же сайта.

Если что-то не работает

Что видитеЧто делать
auth_required или auth_expiredВхода нет или он истёк: выполните uvx kwork-mcp@1.5.2 login и перезапустите клиент
account_binding_requiredВы входили в несколько аккаунтов: укажите нужный в KWORK_EXPECTED_USER_ID или удалите лишний вход командой uvx kwork-mcp@1.5.2 logout <user_id>
Непонятно, какой аккаунт и сайт использует серверuvx kwork-mcp@1.5.2 status покажет это без запросов к Kwork
Сервер не стартует, «некорректная конфигурация: …»Проверьте названные переменные KWORK_* в конфиге клиента
«KWORK_ENABLE_WRITES удалена в 1.5.0»Замените её на KWORK_WRITES=off, confirm или auto
write_disabledСервер запущен с KWORK_WRITES=off, доступно только чтение
captchaВойдите в Kwork в браузере, пройдите капчу, затем повторите login
Claude Desktop не видит серверВозьмите блок для Claude Desktop из вывода login (в нём полный путь к uvx) или укажите путь из which uvx, затем перезапустите приложение
ambiguous_write с related_write_idОтправка с неизвестным результатом блокирует новые. Попросите агента выполнить reconcile_write для этого ID
Сверка долго не сходитсяПроверьте операцию на сайте Kwork, указанном в поле site у pending-writes, и зафиксируйте исход вручную (команды ниже)

Ручная фиксация исхода запускается с теми же KWORK_* переменными, что у сервера:

uvx kwork-mcp@1.5.2 pending-writes
uvx kwork-mcp@1.5.2 resolve-write <write_id> succeeded   # операция на Kwork прошла
uvx kwork-mcp@1.5.2 resolve-write <write_id> absent      # операции на Kwork нет

Инструменты

Чтение:

ИнструментЧто делает
account_statusКакой аккаунт подключён, включена ли запись, есть ли несверенные отправки
get_connectsБаланс коннектов
discover_projects, get_projectПроекты биржи: избранные категории, вся биржа или выбранные категории, фильтры по цене и откликам
get_exchange_infoСводка по бирже
list_my_offers, get_offerВаши отклики
list_worker_orders, get_order_detailsВаши заказы как продавца
list_dialogs, get_dialogДиалоги и сообщения
list_my_kworks, get_kwork_detailsВаши кворки
get_user_info, search_usersПрофили пользователей
list_categories, list_favorite_categoriesКатегории
list_notificationsУведомления

Запись: prepare_write → commit_write, а также get_write_status и reconcile_write. Поддерживаются отклик на проект, удаление отклика, отправка, правка и удаление сообщения, отметка диалога прочитанным, сдача заказа на проверку и запуск или пауза кворка.

Безопасность

  • Логин, пароль и прокси вводятся только в kwork-mcp login через скрытый ввод и не попадают в конфиг клиента.
  • Сервер работает только с аккаунтом, который вы подтвердили при входе (если аккаунтов несколько, с указанным в KWORK_EXPECTED_USER_ID), и проверяет его перед каждой записью.
  • Тексты проектов, профилей и сообщений помечаются как внешние данные, а не инструкции для агента.
  • Токен лежит в файлах с правами 0600. Приложение их не шифрует, поэтому используйте шифрование диска.
  • Лимиты запросов к Kwork общие для всех процессов одного аккаунта.

Подробно: модель безопасности, настройки, архитектура, переход с 0.2.x.

Разработка

git clone https://github.com/simonether/kwork-mcp.git
cd kwork-mcp
uv sync --locked --dev
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest tests/ -q --cov=kwork_mcp

Для запуска из исходников в конфиге клиента используйте uv --directory /path/to/kwork-mcp run kwork-mcp вместо uvx. Правила для изменений и устройство кода описаны в AGENTS.md.

Лицензия

MIT

Questions fréquentes

Qu'est-ce que Kwork ?

Account-bound, typed and durable stdio MCP gateway for the Kwork freelance marketplace

Comment installer Kwork ?

Il s'exécute sur votre machine. Dans Claude Code : claude mcp add kwork -e 'KWORK_EXPECTED_USER_ID=<KWORK_EXPECTED_USER_ID>' -e 'KWORK_EXPECTED_USERNAME=<KWORK_EXPECTED_USERNAME>' -e 'KWORK_WRITES=confirm' -e 'KWORK_SITE=ru' -e 'KWORK_TIMEOUT=30' -e 'KWORK_STATE_DIR=<KWORK_STATE_DIR>' -e 'KWORK_PERSIST_TOKEN=true' -e 'KWORK_RPS_LIMIT=2' -e 'KWORK_BURST_LIMIT=4' -e 'KWORK_ROUTE_RPS_LIMIT=1' -e 'KWORK_ROUTE_BURST_LIMIT=2' -e 'KWORK_RATE_WAIT_TIMEOUT=20' -e 'KWORK_AUTH_LOCK_TIMEOUT=90' -e 'KWORK_READ_ATTEMPTS=3' -e 'KWORK_RETRY_BACKOFF_BASE=0.5' -e 'KWORK_RETRY_BACKOFF_MAX=8' -e 'KWORK_CIRCUIT_FAILURE_THRESHOLD=3' -e 'KWORK_CIRCUIT_OPEN_SECONDS=30' -e 'KWORK_PREPARATION_TTL_SECONDS=600' -e 'KWORK_WRITE_LEASE_SECONDS=120' -e 'KWORK_RECONCILIATION_MIN_AGE_SECONDS=15' -e 'KWORK_RECONCILIATION_ABSENCE_CONFIRMATIONS=2' -e 'KWORK_RECONCILIATION_ABSENCE_INTERVAL_SECONDS=15' -e 'KWORK_STATE_RETENTION_DAYS=30' -e 'KWORK_LOG_LEVEL=INFO' -- uvx kwork-mcp==1.5.2. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour Kwork ?

Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.

Kwork est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient Kwork ?

Il est publié par simonether. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.