Conecta tu cuenta de freelancer de Kwork con agentes de IA para buscar proyectos, gestionar diálogos y preparar respuestas u ofertas.
También conocido como simonether/kwork-mcp, kwork-mcp
- Stars
- 6
- Herramientas
- —
- Descargas, 30 días
- 482
- Última versión
- 1.5.2
- Último commit
- 14 nov 2026
- Licencia
- MIT
¿Qué es Kwork MCP?
Conecta tu cuenta de freelancer de Kwork con agentes de IA para buscar proyectos, gestionar diálogos y preparar respuestas u ofertas.
Resumen generado a partir del README del proyecto
Acerca del MCP server de Kwork
Los freelancers que usan Kwork pueden conectar sus cuentas a agentes de IA como Claude Desktop, Cursor o Claude Code para automatizar gran parte de su flujo de trabajo diario. Este MCP server permite que un agente busque nuevos proyectos, monitoree mensajes no leídos, verifique el estado de los pedidos y gestione conexiones. Está diseñado para usuarios de macOS o Linux que ejecuten Python 3.12 hasta 3.14 con uv.
Los usuarios interactúan con la plataforma pidiéndole al agente que encuentre trabajos específicos, como proyectos de bots de Telegram dentro de un presupuesto determinado, o que redacte respuestas para diálogos con clientes. El servidor incluye un mecanismo de seguridad donde acciones como enviar ofertas o mensajes requieren la confirmación explícita del usuario por defecto. Puedes configurar el nivel de autonomía mediante la variable KWORK_WRITES, eligiendo entre confirmación manual, envío automático o modo de solo lectura.
La configuración requiere un comando de inicio de sesión único que almacena un token de forma segura en tu máquina local sin guardar contraseñas en las configuraciones del cliente. El servidor es compatible tanto con kwork.ru como con kwork.com, asegurando que tu negocio de freelance se mantenga organizado a través de una única interfaz impulsada por IA.
Qué puedes hacer con él
- 1Encontrar proyectos freelance específicosPide al agente que busque proyectos recientes de bots de Telegram con un presupuesto superior a 20,000 ₽.
- 2Gestionar la comunicación con clientesSolicita un resumen de los mensajes no leídos y pide al agente que sugiera respuestas adecuadas.
- 3Redactar y enviar ofertas de proyectosHaz que el agente prepare una respuesta específica para un ID de proyecto y envíala tras aprobar el texto.
- 4Monitorear la cuenta y el estado de los pedidosConsulta tu saldo actual de conexiones y verifica qué pedidos requieren tu atención inmediata.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar Kwork MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar Kwork MCP en Claude Code
$ claude mcp add kwork-mcp -- uvx kwork-mcpInstalar Kwork MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"kwork-mcp": {
"command": "uvx",
"args": [
"kwork-mcp"
]
}
}
}Instalar Kwork MCP en VS Code
.vscode/mcp.json
{
"servers": {
"kwork-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"kwork-mcp"
]
}
}
}Instalar Kwork MCP en VS Code CLI
$ code --add-mcp '{"name":"kwork-mcp","type":"stdio","command":"uvx","args":["kwork-mcp"]}'Instalar Kwork MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"kwork-mcp": {
"command": "uvx",
"args": [
"kwork-mcp"
]
}
}
}Instalar Kwork MCP en Codex
$ codex mcp add kwork-mcp -- uvx kwork-mcpInstalar Kwork MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.kwork-mcp] command = "uvx" args = ["kwork-mcp"]
Instalar Kwork MCP en Gemini CLI
$ gemini mcp add -s user kwork-mcp uvx -- kwork-mcpInstalar Kwork MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"kwork-mcp": {
"command": "uvx",
"args": [
"kwork-mcp"
]
}
}
}Configuración
KWORK_AUTH_LOCK_TIMEOUTMaximum seconds to wait for account credential-store authentication coordination
KWORK_BURST_LIMITShared account-level token bucket capacity
KWORK_CIRCUIT_FAILURE_THRESHOLDShared route failures before opening the circuit
KWORK_CIRCUIT_OPEN_SECONDSBase shared circuit-open interval in seconds
KWORK_EXPECTED_USERNAMEOptional second account identity check
KWORK_EXPECTED_USER_IDKwork user ID to serve; optional when kwork-mcp login bound a single account, required when several are bound
KWORK_LOG_LEVELGateway stderr log level: DEBUG, INFO, WARNING or ERROR
KWORK_PERSIST_TOKENUse the verified account-scoped credential store; required for normal server startup
KWORK_PREPARATION_TTL_SECONDSSafe write preparation lifetime
KWORK_RATE_WAIT_TIMEOUTMaximum seconds to wait for shared rate-limit admission
KWORK_READ_ATTEMPTSMaximum attempts for retry-safe read requests only
KWORK_RECONCILIATION_ABSENCE_CONFIRMATIONSComplete absent observations required before a terminal result
KWORK_RECONCILIATION_ABSENCE_INTERVAL_SECONDSMinimum interval between absent observations (1-300 seconds)
KWORK_RECONCILIATION_MIN_AGE_SECONDSMinimum age before ambiguous-write read-back (1-300 seconds)
KWORK_RETRY_BACKOFF_BASEInitial retry backoff for retry-safe reads, in seconds
KWORK_RETRY_BACKOFF_MAXMaximum retry backoff for retry-safe reads, in seconds
KWORK_ROUTE_BURST_LIMITShared per-route token bucket capacity
KWORK_ROUTE_RPS_LIMITShared per-route token refill rate
KWORK_RPS_LIMITShared account-level token refill rate
KWORK_SITEKwork site: ru (kwork.ru) or com (kwork.com); kwork.com has no project exchange
KWORK_STATE_DIRAbsolute private directory shared by gateway processes for the same account
KWORK_STATE_RETENTION_DAYSRetention for terminal durable write records
KWORK_TIMEOUTKwork request timeout in seconds (1-120)
KWORK_WRITESSending to Kwork: confirm asks the user before each send (client dialog or chat), auto lets the agent send, off is read-only
KWORK_WRITE_LEASE_SECONDSDurable one-writer lease duration in seconds
| Nombre | Descripción | Tipo |
|---|---|---|
| KWORK_AUTH_LOCK_TIMEOUT | Maximum seconds to wait for account credential-store authentication coordination | |
| KWORK_BURST_LIMIT | Shared account-level token bucket capacity | |
| KWORK_CIRCUIT_FAILURE_THRESHOLD | Shared route failures before opening the circuit | |
| KWORK_CIRCUIT_OPEN_SECONDS | Base shared circuit-open interval in seconds | |
| KWORK_EXPECTED_USERNAME | Optional second account identity check | |
| KWORK_EXPECTED_USER_ID | Kwork user ID to serve; optional when kwork-mcp login bound a single account, required when several are bound | |
| KWORK_LOG_LEVEL | Gateway stderr log level: DEBUG, INFO, WARNING or ERROR | |
| KWORK_PERSIST_TOKEN | Use the verified account-scoped credential store; required for normal server startup | |
| KWORK_PREPARATION_TTL_SECONDS | Safe write preparation lifetime | |
| KWORK_RATE_WAIT_TIMEOUT | Maximum seconds to wait for shared rate-limit admission | |
| KWORK_READ_ATTEMPTS | Maximum attempts for retry-safe read requests only | |
| 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_RECONCILIATION_MIN_AGE_SECONDS | Minimum age before ambiguous-write read-back (1-300 seconds) | |
| 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_ROUTE_BURST_LIMIT | Shared per-route token bucket capacity | |
| KWORK_ROUTE_RPS_LIMIT | Shared per-route token refill rate | |
| KWORK_RPS_LIMIT | Shared account-level token refill rate | |
| KWORK_SITE | Kwork site: ru (kwork.ru) or com (kwork.com); kwork.com has no project exchange | |
| KWORK_STATE_DIR | Absolute private directory shared by gateway processes for the same account | |
| KWORK_STATE_RETENTION_DAYS | Retention for terminal durable write records | |
| KWORK_TIMEOUT | Kwork request timeout in seconds (1-120) | |
| 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_WRITE_LEASE_SECONDS | Durable one-writer lease duration in seconds |
Verificaciones automáticas
Ejecutado 13 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesibleAprobado
- Licencia de código abierto (OSI)Aprobado
- Commit o lanzamiento en el último añoAprobado
- El nombre del paquete no es similar a un paquete popularAprobado
- El endpoint remoto usa HTTPSNo verificado
- Las herramientas destructivas están etiquetadasNo verificado
- Sin instrucciones ocultas para el modeloAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasAprobado
README
Ver en GitHubkwork-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
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.
Лицензия
Preguntas sobre Kwork MCP
¿Cómo agrego Kwork MCP a Claude Code?
Ejecuta claude mcp add kwork-mcp -- uvx kwork-mcp en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego Kwork MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Cómo inicio sesión en mi cuenta de Kwork?
Ejecuta el comando uvx kwork-mcp@1.5.2 login en tu terminal. Se te solicitará tu usuario y contraseña de forma segura.
¿Puede el agente de IA enviar mensajes u ofertas automáticamente?
Sí, puedes configurar la variable KWORK_WRITES en 'auto' para envío automático, 'confirm' (por defecto) para requerir tu aprobación, o 'off' para acceso de solo lectura.