Karlancer MCP Server

Get started · Features · MCP tools · Security · Deployment · فارسی

Why this exists

A self-hosted Model Context Protocol (MCP) server for connecting a Karlancer account to an AI assistant. The assistant can inspect freelance opportunities, prepare proposals, and manage permitted conversations through scoped, human-approved tools. Each person connects their own account via a Persian RTL portal; no one shares their Karlancer password with an AI client.

No built-in autonomous model, paid credit purchasing, or guaranteed winning proposals.

Related MCP server: ConnectPX MCP OAuth Demo

Features

• Sending is disabled by default for newly connected accounts.

• Financial floor, maximum duration, daily caps and manual/AI delegation remain human-managed.

• A preparation operation creates a draft; it does not send a real proposal.

• Ambiguous submissions result in UNKNOWN and are never blindly replayed.

• MCP tools cannot purchase premium credits or change owner-only policy.

• Tenant ownership and OAuth scopes limit all accessible records and tools.

Architecture

flowchart LR
  Agent["AI client<br/>MCP + OAuth"] --> Auth["OAuth / PKCE"]
  Portal["RTL web portal<br/>Human approval"] --> Auth
  Auth --> MCP["Streamable HTTP MCP<br/>Tool and policy gates"]
  Portal <--> DB[("Encrypted SQLite")]
  MCP <--> DB
  MCP <--> Karlancer["Karlancer website<br/>Observed endpoints"]

Quick start

Prerequisites: Docker Engine + Compose v2, HTTPS domain, and outbound connectivity to Karlancer. Development requires Node.js 24+ for node:sqlite.

git clone https://github.com/JavadRostami3/karlancer-mcp-server.git
cd karlancer-mcp-server
cp .env.example .env
openssl rand -hex 32

Configure the example environment file (do not commit the real one):

BASE_URL=https://mcp.example.com
MASTER_KEY=REPLACE_WITH_64_HEX_CHARACTERS
OWNER_PHONE_HASH=REPLACE_WITH_64_HEX_CHARACTERS
PORT=8940
DB_PATH=/app/data/state.sqlite

Generate OWNER_PHONE_HASH from the initial administrator's Iranian phone normalized to ten digits (9xxxxxxxxx, omitting 98 or a leading 0):

OWNER_PHONE="9xxxxxxxxx" node -e "const {createHash}=require('node:crypto');const p=process.env.OWNER_PHONE;if(!/^9[0-9]{9}$/.test(p))throw Error('Expected 9xxxxxxxxx');console.log(createHash('sha256').update(p).digest('hex'))"

Replace the two placeholders in your private .env. Use the output of openssl as MASTER_KEY. Never regenerate the master key for a database you want to keep.

docker compose up -d --build
curl -fsS http://127.0.0.1:18940/healthz

The container is bound to 127.0.0.1:18940 by default. Set up a trusted HTTPS reverse proxy for the exact BASE_URL hostname. Then open your public portal at https://mcp.example.com/ for Karlancer OTP onboarding. Additional people are admitted by owner invitation. See deployment.

Connect an AI client

Register the remote MCP endpoint https://mcp.example.com/mcp in a client supporting Streamable HTTP + OAuth authorization code + resource indicators. Complete the browser authorization and grant only the required scopes.

Some hosts accept a remote definition shaped like this. Exact configuration keys vary by host and version:

{
  "servers": {
    "karlancer": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

The issuer is at /oidc. Protected resource metadata is at /.well-known/oauth-protected-resource/mcp. Client registration uses /oidc/reg. Read OAuth integration for exact requirements.

MCP tools

19 tools, advertised according to tenant-specific OAuth scopes:

See src/tool-catalog.ts for tool schemas and docs/oauth.md for scopes.

Proposal safety lifecycle

flowchart TD
  Search["Inspect project and policy"] --> Draft["Prepare immutable draft"]
  Draft --> Gate{"Owner rules + credits pass?"}
  Gate -- No --> Stop["Blocked with reason"]
  Gate -- Yes --> Submit["Submit with stable idempotency key"]
  Submit --> Result{"Authoritative response?"}
  Result -- Yes --> Confirm["Confirmed / actionable result"]
  Result -- Uncertain --> Investigate["UNKNOWN — check operation status;<br/>never blindly resend"]

Commercial terms in outgoing replies can require an owner decision; merely approving a draft does not itself send the reply.

Security

• OAuth scopes: mcp plus profile:read, profile:write, projects:read, proposals:read, proposals:write, conversations:read, conversations:write.

• Multi-tenancy: records and account sessions belong to one bound user, with strict ownership checks.

• Encrypted storage: confidential session material is tenant-bound and AES-256-GCM protected.

• Strict OAuth redirects: HTTPS redirect URI validation and PKCE for public clients.

• Safe write semantics: draft preparation, input checks, financial policy, idempotency keys and uncertain-result handling.

• Logs: structured safe diagnostic events exclude authorization headers, OTPs, cookies and request/response bodies.

There is no security warranty. Self-hosters must harden TLS, backups, permissions, dependencies and infrastructure. Report issues privately via SECURITY.md.

Development and tests

npm ci
npm run build
npm test

# Set up your private .env before running locally:
npm run dev

The regression suite uses local HTTP fixtures, real OAuth provider flows and MCP transport without sending live employer messages or paid operations. GitHub Actions runs build/tests on pushes and PRs.

src/                  MCP tools, account adapter, OAuth, domain and portal
tests/                Local regression tests
public/               RTL portal assets and licensed SVG icons
docs/                 Setup, OAuth and Persian guide
.github/workflows/    CI
Dockerfile            Node 24 multi-stage image
compose.yaml          Loopback-only Compose service
.env.example          Safe configuration template

No API key is needed by this server. The MCP host/client supplies its own model. This project exposes tools and enforces policy; it is not a background AI agent.

No. Upstream endpoints are observed website interfaces. Their behavior can change without notice. Terms, quotas, account state and login requirements apply.

Contributing and license

Contributions are welcome for safer workflows, compatibility, localization and fixture coverage. Please read CONTRIBUTING.md. Report vulnerabilities privately, not in public issues.

Licensed under MIT. Karlancer is a trademark of its respective owner. This independent project is not an official product.

Own your workflow. Keep humans in control.

Open an issue · Deployment · فارسی