Kolay CLI and MCP Server
Disclaimer. This is an independent, community-maintained project. It is not an official product of Kolay Yazilim A.S. and carries no endorsement, warranty, or support from the company. All write operations target live HR data — there is no sandbox. You are solely responsible for your API token and the actions performed through this software.
Command-line interface and AI integration server for Kolay IK. Manage employees, leaves, timelogs, trainings, payroll, and organizational structure from the terminal or through any AI assistant that speaks Model Context Protocol.
Quick Start
# 1. Install
pipx install kolay-cli # or: pip install kolay-cli
# 2. Authenticate
kolay setup # guided first-time setup
# 3. Verify
kolay doctor # health check
Requires Python 3.10 or later.
What This Package Provides
| Binary | Purpose |
|---|---|
kolay |
Interactive CLI for terminal use |
kolay-mcp |
MCP server binary for AI clients |
The same pip install kolay-cli command installs both.
Documentation
Detailed guides are maintained separately for each component:
| Guide | Audience | Contents |
|---|---|---|
| docs/CLI.md | Terminal users, scripts, CI pipelines | Full command reference, output modes, shell completion, local security |
| docs/MCP.md | AI integrators, platform teams | Client setup (ChatGPT, Claude, Gemini, Cursor, etc.), tool catalogue, architecture |
| docs/BOX.md | Self-hosting teams, IT administrators | Docker Compose deployment, GPU/CPU modes, troubleshooting |
| docs/SECURITY.md | Security reviewers, compliance officers | Encryption, PII masking, DLP, rate limiting, audit trail |
Connecting AI Assistants
ChatGPT
- Open chatgpt.com → Settings → Apps & Connectors.
- Enable Developer Mode under Advanced settings.
- Click Create. Enter:
- Name:
Kolay IK - URL:
https://kolay.up.railway.app/mcp
- Name:
- Add a custom header:
X-Kolay-Token→ your Kolay API token. - Save. Open a new chat, attach the Kolay IK app, and ask.
Claude Desktop
kolay mcp install # writes claude_desktop_config.json automatically
Or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"kolay-ik": {
"command": "kolay-mcp",
"args": []
}
}
}
Other Clients
Local (stdio): run kolay-mcp as a subprocess.
Remote (HTTP): point to https://kolay.up.railway.app/mcp with an X-Kolay-Token header.
See docs/MCP.md for Gemini CLI, Cursor, VS Code, Windsurf, Zed, Mistral, and Perplexity instructions.
Self-Hosted AI (Kolay AI Box)
Run a fully private AI HR assistant on your own hardware. No cloud dependency.
cd box
make dev # CPU mode (Mac, laptop)
# or
make up # GPU mode (NVIDIA)
Open http://localhost:3000. See docs/BOX.md for full setup instructions.
Security Overview
| Layer | What it protects |
|---|---|
| OS keychain | API token at rest (macOS Keychain, GNOME Keyring, Windows Vault) |
| AES-256-GCM | Local config file encryption (opt-in) |
| TLS 1.2+ | All network traffic |
| PII masking | Names and emails replaced with pseudonyms before reaching the LLM |
| Egress DLP | Last-mile redaction of TC Kimlik and IBAN patterns |
| Rate limiter | Per-token sliding window to prevent abuse |
| Circuit breaker | Stops infinite AI tool-calling loops |
| Audit log | Local append-only log of all write operations, with 5 MB rotation |
Two profiles are available via KOLAY_SECURITY_PROFILE:
standard(default): TLS, token auth, rate limiting, human-in-the-loop for destructive ops.enterprise: Adds AES-256-GCM encryption, DLP scanning, HMAC execution receipts.
Full details: docs/SECURITY.md.
Development
# install with test dependencies
pip install -e ".[test,dev]"
# run tests
uv run --extra test pytest tests/ -v
Stack
- Python 3.10+
- Typer + Rich (CLI)
- FastMCP 3.x (MCP protocol engine)
- AES-256-GCM + PBKDF2 (local encryption)
- Qdrant + FastEmbed (RAG, optional)
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General / server error |
| 2 | Bad input / validation |
| 3 | Not found |
| 4 | Auth / permission denied |
| 5 | Conflict |
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for kolay-cli 0.13.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kolay_cli-0.13.3.tar.gz | 258.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kolay_cli-0.13.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 493.5 kB
Release files / kolay_cli-0.13.3.tar.gz
| Download URL | kolay_cli-0.13.3.tar.gz |
|---|---|
| Size | 258.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
44724cdd5deb37a6d8566fb4fdcedcbe9d23e6506425291c550c914dbf669c4f
|
|
BLAKE2b-256 checksum How to use checksums |
1936b483c9deb0096cea001acf910e1e555e82c206514f6ca40f556153098087
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.9 {"installer":{"name":"uv","version":"0.10.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / kolay_cli-0.13.3-py3-none-any.whl
| Download URL | kolay_cli-0.13.3-py3-none-any.whl |
|---|---|
| Size | 235.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5f86258bc0dcdb9080796574b60847cbc5f6f8a92c3160198de621cf4b4ec641
|
|
BLAKE2b-256 checksum How to use checksums |
e3b0da796ab91480c8da7ddbaa050b34b517c29689f43db1769f7586f42665b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.9 {"installer":{"name":"uv","version":"0.10.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
