# Kwork MCP server

> Connects your Kwork freelance account to AI agents to search for projects, manage dialogues, and prepare responses or offers.

- Repository: https://github.com/simonether/kwork-mcp
- Page: https://hostedmcp.org/servers/simonether/kwork-mcp
- Transport: stdio
- Stars: 6
- License: MIT
- Latest version: 1.5.2

## Install

### Claude Code

```sh
claude mcp add kwork-mcp -- uvx kwork-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "kwork-mcp": {
      "command": "uvx",
      "args": [
        "kwork-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "kwork-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "kwork-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"kwork-mcp","type":"stdio","command":"uvx","args":["kwork-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "kwork-mcp": {
      "command": "uvx",
      "args": [
        "kwork-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add kwork-mcp -- uvx kwork-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.kwork-mcp]
command = "uvx"
args = ["kwork-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user kwork-mcp uvx -- kwork-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "kwork-mcp": {
      "command": "uvx",
      "args": [
        "kwork-mcp"
      ]
    }
  }
}
```

## Environment variables

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

## FAQ

### How do I log in to my Kwork account?

Run the command `uvx kwork-mcp@1.5.2 login` in your terminal. It will securely ask for your login and password.

### Can the AI agent send messages or offers automatically?

Yes, you can configure the `KWORK_WRITES` variable to 'auto' for automatic sending, 'confirm' (default) to require your approval, or 'off' for read-only access.
