ClawHire MCP

Employer-facing MCP for China's first agent-native hiring marketplace.

ClawHire lets hiring managers post jobs, search candidates, and receive applications — all through natural language conversation with Claude or any MCP-compatible AI assistant. Backed by WonderCV's resume database and existing HR infrastructure.

What This Is

ClawHire is one half of a two-sided marketplace:

Candidates                              Employers
    │                                       │
resume-agent-mcp                    clawhire-mcp (this repo)
    │                                       │
    └──────── WonderCV Backend ─────────────┘
                    │
              PostgreSQL (existing WonderCV DB)

• resume-agent-mcp — Candidate-facing. Resume analysis, profile publishing, job applications.

• clawhire-mcp (this repo) — Employer-facing. Job posting, candidate search, application management.

Both share WonderCV's existing Django backend, company database, and profession taxonomy. This is NOT a standalone product — it's an MCP layer on top of WonderCV's existing hiring infrastructure.

Why It Exists

The thesis: China is in an AI-agent boom. Companies hiring for white-collar roles increasingly want people who can work with AI agents. But no hiring platform treats AI-agent fluency as a first-class hiring signal.

ClawHire does. Candidates who use MCP tools are automatically tagged with AI fluency badges. Employers can filter for agent-fluent talent. This signal is impossible to replicate on traditional job boards.

Three Categories of Candidates

Not all candidates are equal. The system handles three distinct pools:

Category conversions:

• 3 → 2: Candidate responds to outreach email or opts in via GUI

• 2 → 1: Candidate links MCP session to their WonderCV account (automatic upgrade)

• Conversions are one-way (upward only)

Company blocklist: Candidates can block specific companies (e.g. current employer) from seeing their profile. Enforced at query time.

Architecture

Existing WonderCV Models We Reuse (DO NOT DUPLICATE)

New Models We Add (only 2)

Data Unit Conventions

These MUST match existing WonderCV conventions:

Available Tools (7)

Quota Tiers (daily limits)

All alpha users get the Alpha tier for free.

Quick Start

Install & Build

git clone https://github.com/WonderCV/clawhire-mcp.git
cd clawhire-mcp
npm install
npm run build

Configure

cp .env.example .env

Edit .env:

CLAWHIRE_API_BASE_URL=https://api.wondercv.cn/cv/v1/mcp/hiring
CLAWHIRE_API_KEY=your_api_key_here    # Leave as-is for mock mode
LOG_LEVEL=info

Mock mode: If CLAWHIRE_API_KEY is missing or your_api_key_here, the server returns realistic mock data for all endpoints. Useful for development without the backend.

Add to Claude

In your MCP config (e.g. ~/.claude.json or Claude Desktop settings):

{
  "mcpServers": {
    "clawhire": {
      "command": "node",
      "args": ["/absolute/path/to/clawhire-mcp/dist/server.js"],
      "env": {
        "CLAWHIRE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Try It

After connecting, tell Claude:

• "Register my company — we're TechCorp in Shanghai, email hr@techcorp.com"

• "Post a job for Senior Product Manager, remote OK, 30-50k/month"

• "Search for AI-fluent product managers in Shanghai with 3+ years experience"

• "Show me candidate details for [candidate_id]"

• "Send an outreach invite to [candidate_ref] for the PM role"

Development

npm run dev          # Watch mode (auto-recompile on changes)
npm run build        # Single build
npm run typecheck    # Type check without emitting
npm start            # Run compiled server

Project Structure

src/
├── server.ts           # MCP server entry, tool registration, JSON schema conversion
├── types.ts            # All TypeScript types (aligned with WonderCV models)
├── session.ts          # In-memory session management + quota tracking
├── backend-api.ts      # WonderCV backend API client (with mock fallback)
└── tools/
    ├── index.ts                # Tool registry
    ├── register_company.ts     # Creates HrAccount + Company
    ├── post_job.ts             # Wraps Jobs model (years→days conversion)
    ├── list_jobs.ts            # Paginated job list with stats
    ├── search_candidates.ts    # Marketplace + database pools, AI fluency filter
    ├── view_candidate.ts       # Visibility-enforced profile view + anonymization
    ├── list_applications.ts    # Application list with match scores
    └── request_outreach.ts     # Database candidate invitation (rate-limited)

Adding a New Tool

1. Create src/tools/your_tool.ts implementing the Tool<Input> interface

2. Define input schema with Zod

3. Implement execute(input) returning ToolResult

4. Export from src/tools/index.ts and add to allTools array

5. The server auto-registers it via the tool registry

Backend API Pattern

All tools follow the same pattern:

// 1. Validate session
const session = getSession(input.session_id);
if (!session) return errorResult('INVALID_SESSION', '...');

// 2. Check quota (for metered tools)
const remaining = getRemainingQuota(session, 'searches');
if (remaining <= 0) return errorResult('QUOTA_EXCEEDED', '...');

// 3. Call backend
const result = await backendApi.searchCandidates(input);

// 4. Consume quota AFTER success (not before)
checkAndIncrementUsage(session, 'searches');

// 5. Format and return
return { content: [{ type: 'text', text: JSON.stringify(formatted) }], isError: false };

Known Issues (v0.1.0)

See KnownIssues.md for full details.

Alpha verdict: Ship to alpha (<50 employers), not to GA.

Roadmap

v0.1 (current) — Alpha Foundation

• 7 employer tools (register, post, search, view, applications, outreach, list)

• Three-category candidate model

• AI fluency badges

• Anonymization for privacy

• Daily quota system

v0.2 — Marketplace Core

• Persistent session storage (Redis or backend rehydration)

• Backend authoritative quota metering

• Replace zodToJsonSchema with zod-to-json-schema library

• Candidate-side tools in resume-agent-mcp (publish, apply, browse jobs)

• LLM-based match scoring

• Test suite

v0.3 — Growth

• Company verification automation (Tianyancha API)

• Application status management (shortlist, reject)

• Paid tier billing (via existing JobOrders + Alipay/WeChat Pay)

• Global aggregate stats

Related

• resume-agent-mcp — Candidate-side MCP

• WonderCV — Resume platform

• Full product plan — Architecture decisions and detailed specs

License

MIT