Skip to main content
Glama
Freelance MCP server

Freelance MCP server

Official

Freelance MCP server

Where this lives. This repository is the distributable copy of the freelance MCP server. It is split out of the Clockbook enterprise monorepo (packages-enterprise/freelance/mcp), which remains the source of truth - changes land there and are mirrored here with git subtree. Two things are monorepo-only and deliberately absent: the live e2e harness, which boots the subgraph against a local Mongo, and the docs-catalogue generator, which writes into the freelance surface package.

npm run build validates all 23 tool documents against the subgraph SDL when it can reach it. Outside the monorepo it says so and skips, rather than failing a build it cannot perform. Point FREELANCE_SCHEMA_DIR at freelance/server/src/graphql/schema (and npm i --no-save graphql) to run that check from a standalone clone.

Point any MCP-capable AI at the Clockbook freelance marketplace: the talent directory, job postings, proposals, contracts with milestones and escrow, the wallet, messages and notifications. Twenty-three tools over the same GraphQL subgraph the freelance surface itself calls.

Works with Claude Desktop, Claude Code, Cursor, or anything else that speaks MCP over stdio.


What you need first

A platform API token. This module issues no credentials of its own. The platform does: mint a Secret API token from your Account page. Such a token already authenticates against the freelance subgraph with no further setup.

An agent identity registered against it — strongly recommended. An unregistered token arrives holding your entire seat, because the platform token has no notion of scopes and defineAbilityFor grants Manage to every org member. Registering the token as an agent identity is how you narrow it: the agent gets only the scopes you list, and you can switch it off later. It can never do more than your seat could; scopes only take away.


Related MCP server: Upwork MCP Server

Setup

1. Mint a token

Account page → Secret API tokens → create one. Copy it; you will not see it again.

2. Compute its digest

The raw token is never sent to the server during registration. You register the SHA-256 digest, and you compute it yourself:

node -e "console.log(require('crypto').createHash('sha256').update(process.argv[1]).digest('hex'))" <TOKEN>

That prints 64 lowercase hex characters. Nothing is lost by hashing client-side — whoever can register a token already holds it — and it means the bearer is never a mutation argument, never reaches a resolver, and cannot land in a trace or an error message.

3. Register the agent

Run this against your plane's freelance subgraph, signed in as a person — an agent may not register another agent, or the narrowest credential on the system could mint itself a wider sibling:

mutation {
    registerFreelanceAgentIdentity(
        input: {
            label: "Claude Desktop — my laptop"
            tokenDigest: "<the 64 hex characters from step 2>"
            scopes: [READ_DIRECTORY, READ_OWN]
        }
    ) {
        agentId
        label
        tokenHint
        scopes
    }
}

The scopes, and what each actually unlocks:

Scope

What it allows

READ_DIRECTORY

Read the talent directory and job postings.

READ_OWN

Read your own contracts, proposals, wallet and notifications.

DRAFT

Create and edit draft postings and templates. Nothing that reaches a person.

MESSAGE

Send messages in existing threads.

PROPOSE

Submit and withdraw bids.

HIRE

Publish a requisition, invite, accept a bid, end a contract. Commitments, not money.

SPEND

Fund, release, refund, cash out. The one nobody should grant casually.

Omit scopes entirely and you get READ_DIRECTORY and READ_OWN — read-only, which is the right shape to start with. Add more once you have watched it work.

Revoke at any time with revokeFreelanceAgentIdentity(agentId: "agent_…"). It bites on the agent's very next request, because liveness is part of the per-request lookup and not a nightly sweep.

4. Get the server

It is published to npm as @clockbook-app/freelance-mcp, and the shortest path is not to install it at all — let your MCP client fetch it on demand with npx. That is the wiring shown in the next step, and it is the one to prefer: there is no path to get wrong and no copy to go stale.

To check it runs before wiring anything up:

npx -y @clockbook-app/freelance-mcp

It should print a [freelance-mcp] ready line naming the endpoint and the tool count, then sit waiting for MCP traffic on stdin. Ctrl-C out of it.

From a clone instead

Build from source if you are changing the server, or if you would rather pin an exact tree than a version range. The server runs from dist/, which is gitignored, so the build is not optional:

git clone https://github.com/Clockbook-com/freelance-mcp.git
cd freelance-mcp
npm install
npm run build
echo "$PWD/dist/index.js"   # the absolute path the next step needs

npm run build also validates all 23 tool documents against the freelance subgraph SDL when it can reach it. From a standalone clone it cannot, so it says so and skips rather than failing a check it has no way to perform — see the note at the top of this file for how to run it anyway.

5. Wire it into your client

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
    "mcpServers": {
        "freelance": {
            "command": "npx",
            "args": ["-y", "@clockbook-app/freelance-mcp"],
            "env": {
                "FREELANCE_API_TOKEN": "<your platform API token>",
                "FREELANCE_GRAPHQL_URL": "https://freelance-backend.yantra-app-v1.cdebase.dev/graphql"
            }
        }
    }
}

Restart the client.

Claude Code — same JSON under mcpServers, or:

claude mcp add freelance \
  --env FREELANCE_API_TOKEN=<your platform API token> \
  --env FREELANCE_GRAPHQL_URL=https://freelance-backend.yantra-app-v1.cdebase.dev/graphql \
  -- npx -y @clockbook-app/freelance-mcp

Cursor — .cursor/mcp.json in the project, or ~/.cursor/mcp.json globally. Same mcpServers shape as Claude Desktop.

Running from a clone instead? Swap the command for node and the args for the one absolute path you printed in step 4:

"command": "node",
"args": ["/absolute/path/to/freelance-mcp/dist/index.js"]

The absolute path is not optional there — the client does not run this from your shell's working directory.

6. First test call

Ask the assistant:

Using the freelance tools, who am I?

It should call freelance_get_my_profile and come back with your name, your email and whether your profile is listed in the directory. That one call proves all three things at once: the server started, the endpoint is right, and the token authenticates.

Then try a read that touches the marketplace:

Find me three people on the freelance marketplace who can do video editing.


Configuration

Setting

Environment variable

Config file key

Default

API token

FREELANCE_API_TOKEN

apiToken

(none — calls refuse)

Endpoint

FREELANCE_GRAPHQL_URL

graphqlUrl

https://freelance-backend.yantra-app-v1.cdebase.dev/graphql

Environment wins over the file, always. The config file exists for the case the env lane handles badly — driving three clients without pasting the same secret into three JSON files that sync to three different places:

// ~/.freelance-mcp/config.json
{
    "apiToken": "…",
    "graphqlUrl": "https://freelance-backend.yantra-app-v1.cdebase.dev/graphql"
}

Point FREELANCE_MCP_CONFIG elsewhere if you want the file somewhere else.

Set the endpoint if you are not on yantra-app-v1. A deployment plane is a whole separate database, so a request that lands on the wrong one does not fail — it silently addresses an organization you do not have. The host is freelance-backend.<your-plane>.

Note that clockbook-app-v10 is also live, and the installed yantra-job-freelancer connector (v1.1.1) still names it. A token from one plane gets Not a member of organization "<org>" on the other — a 403, not a connection error, so the address looks fine right up until it is not.


The tools

Reads first, then the writes — which is also the order to use them in, because an id comes from a list and a title is never an id.

Directory and profile: freelance_get_my_profile, freelance_search_talent, freelance_get_profile

Job postings: freelance_search_jobs (the whole marketplace), freelance_list_org_jobs (your organization's own, any status), freelance_get_job, freelance_create_job

Proposals: freelance_list_my_proposals, freelance_list_proposals_for_job, freelance_submit_proposal, freelance_accept_proposal

Contracts and milestones: freelance_list_contracts, freelance_get_contract, freelance_add_milestone, freelance_submit_milestone, freelance_fund_milestone, freelance_refund_milestone, freelance_approve_milestone

Wallet: freelance_get_wallet

Messaging: freelance_list_conversations, freelance_get_conversation, freelance_send_message

Notifications: freelance_list_notifications

Two tools have side effects that are easy to miss: freelance_get_conversation marks the thread read, which clears the other side's unread signal — so do not sweep an inbox to summarise it. And freelance_send_message cannot be undone: there is no edit and no delete.


Money: the acknowledgement gate

Three tools move real money, and all three need the SPEND scope, which the server enforces:

  • freelance_fund_milestone — commit a milestone's amount to escrow. Reversible.

  • freelance_refund_milestone — take it back out. Reversible.

  • freelance_approve_milestone — on a funded milestone, this releases the escrow to the freelancer. Not reversible by anything in this product.

That last one requires acknowledge: true, and the flag means one specific thing: the person the agent is acting for was told the amount and the payee and said yes to that release. Omit it on a funded milestone and the call is refused — usefully:

This will release $1,250.00 USD to Dana Okafor, and it cannot be undone from
here. Re-send approveFreelanceContractMilestone with acknowledge: true to
release the escrow. [FREELANCE_ACKNOWLEDGEMENT_REQUIRED]

That sentence is the one to put in front of a person. The refusal is designed to be read, not logged — which is why the amount and the payee are written into the message itself and not only into extensions.

The gate is per call and never per session. A milestone's amount is editable until it is funded, so an acknowledgement carried over from an earlier call is consent to a different number.


When something is refused

What you see

What it means

[FREELANCE_ACKNOWLEDGEMENT_REQUIRED]

Confirm with the person, then re-send with acknowledge: true.

[FREELANCE_AGENT_SCOPE_REQUIRED]

The agent identity lacks the scope. A human grants it; retrying will not help.

HTTP 401 / HTTP 403

The platform token expired, or its agent identity was revoked. Mint a fresh token, register its digest again, update FREELANCE_API_TOKEN.

Could not reach the freelance backend at …

Wrong plane, or nothing listening. Check FREELANCE_GRAPHQL_URL.

No freelance API token is configured

Neither the env var nor the config file had one. The message names the exact file it looked in.

To see what the server thinks its configuration is, check your client's MCP log. On startup it writes one line to stderr naming the endpoint, where the token came from (env, file or none) and the tool count. It never prints the token or its digest.


Notes for maintainers

The GraphQL documents in src/tools.ts are copies of the ones in freelance/surface/src/api/operations.ts, because the surface is a browser package with its own lockfile and importing it would drag React into a stdio process. Copies drift, and a document that names a field the schema does not have fails whole — "Cannot query field", and that tool stops working.

Two things keep the drift survivable. The field lists here are deliberately slimmer than the surface's: everything these tools return is read by a language model, and the surface's lists exist to paint screens. Fewer fields is both less context burned per row and a smaller drift surface. And every field named here appears in a surface list already known to validate against this schema.

All 23 documents were validated against the subgraph SDL in freelance/server/src/graphql/schema/*.graphql, and every tool inputSchema was checked against the corresponding GraphQL input type — argument names, nested input-object field names and enum vocabularies. Worth redoing after any schema change.

One deliberate divergence: freelance_list_notifications declares side as an enum of FIND_WORK | HIRE_TALENT, while the schema types it as a plain String. A model left to guess sends "find_work" and gets an empty feed, which reads as "no notifications" rather than as an error. If the schema ever gains a real enum, use it and delete the list.

Available Tools

23 tools
freelance_accept_proposalA

Hire a bidder: accepting a proposal MINTS A CONTRACT and returns it. Belongs to the HIRE scope, and the posting must be your organization's. This is a commitment to a person, not a draft - confirm with whoever you are acting for first. It commits no money on its own; funding happens later, per milestone, through freelance_fund_milestone.

Inputs: id (required), weeklyLimit.

freelance_add_milestoneA

Add a milestone to a contract - a named piece of work with an amount and a due date. Client lane: the contract must be your organization's. Belongs to the HIRE scope. Adding one commits no money; it only describes what a later payment would be for.

Inputs: id (required), input (required).

freelance_approve_milestoneA

MOVES MONEY, AND CANNOT BE UNDONE. Approve submitted work, moving the milestone SUBMITTED -> APPROVED -> PAID. On a milestone whose escrowStatus is FUNDED this is the call that RELEASES the escrow: the held money becomes the freelancer's cash-out balance, and nothing in this product can pull it back. Requires the SPEND scope, enforced by the server. ON A FUNDED MILESTONE YOU MUST SEND acknowledge: true, and that flag means one specific thing: the person you are acting for has been told the amount and the payee and has said yes to THIS release. It is not a formality to set by default. Call it without the flag first if you are unsure - the refusal comes back as FREELANCE_ACKNOWLEDGEMENT_REQUIRED and carries the exact amount, currency and payee, which is the sentence to put in front of the person before you re-send with the flag. The flag is per call and never per session: a milestone's amount can change between two calls, so consent to an earlier one is consent to a different number. On a milestone nobody funded, the flag is ignored and this only moves the status.

Inputs: id (required), milestoneId (required), acknowledge.

freelance_create_jobA

Publish a job posting to the marketplace under your organization's name. Belongs to the HIRE scope, and requires an organization context on the token - a personal token with no organization has nothing to post as. THIS IS VISIBLE TO REAL PEOPLE THE MOMENT IT LANDS: freelancers see it in search and can bid on it, so confirm the title, the budget and the description with the person you are acting for before calling this, never off your own reasoning. Set visibility: ORGANIZATION to keep it inside your organization while it is being worked on.

Inputs: input (required).

freelance_fund_milestoneA

MOVES MONEY. Commit a milestone's amount to escrow before the work starts. Requires the SPEND scope, which the server enforces - an agent identity without it is refused with FREELANCE_AGENT_SCOPE_REQUIRED, and the fix is a human granting the scope, not a retry. The money leaves the organization's spendable balance and is HELD: still the organization's, no longer spendable, not yet the freelancer's. No acknowledgement flag is needed because this is reversible - freelance_refund_milestone takes it straight back while the work is unapproved.

Inputs: id (required), milestoneId (required).

freelance_get_contractA

One contract by id, with its milestones and their escrow state. Requires READ_OWN and membership of the contract. READ THIS BEFORE APPROVING ANYTHING: a milestone whose escrowStatus is FUNDED releases real money when approved, and that is the case where freelance_approve_milestone requires acknowledge: true.

Inputs: id (required).

freelance_get_conversationA

One thread and its messages. Requires READ_OWN. NOTE A SIDE EFFECT: reading a conversation MARKS IT READ for this account, which clears the other side's "unread" signal. Do not sweep every thread to summarise an inbox unless the person asked you to - use the unread counts from freelance_list_conversations for that, which change nothing.

Inputs: id (required), limit.

freelance_get_jobA

One job posting in full by id. Requires READ_DIRECTORY. Re-authorized on the server rather than trusted: your own organization sees any of its postings, everybody else sees PUBLIC ones only, and an ORGANIZATION-visibility posting you have no claim to comes back empty rather than refusing - that is the privacy boundary working, not a broken id.

Inputs: id (required).

freelance_get_my_profileA

The freelancer profile belonging to the account this API token authenticates as, including the owner-only fields (email, whether the profile is listed in the directory). Requires READ_OWN. Use this first to confirm which account and organization the token is acting for - every other tool acts as this identity, and there is no argument anywhere that can aim one at somebody else.

Inputs: no named parameters.

freelance_get_profileA

One freelancer from the directory by id, as the public projection shows them. Requires READ_DIRECTORY. Ids come from freelance_search_talent - a name is not an id, and there is no lookup by name.

Inputs: id (required).

freelance_get_walletA

The account's wallet: money available to hire with (toSpend), earnings available to cash out (toCashOut), money committed to milestones (inEscrow), and recent ledger entries. Requires READ_OWN. A READ - it moves nothing. Check toSpend against a milestone's amount BEFORE calling freelance_fund_milestone: funding more than the wallet covers is refused outright and leaves the milestone unfunded rather than half-funded.

Inputs: no named parameters.

freelance_list_contractsA

Contracts where this account is either the freelancer or the client organization. Requires READ_OWN. Pass filter.role to pick a side: FREELANCER is work this account is doing, CLIENT is work it is paying for. Without it you get both, which is rarely what a question means.

Inputs: filter.

freelance_list_conversationsA

Message threads this account takes part in, with unread counts. Requires READ_OWN. A thread is anchored to a posting, a proposal or a contract - that anchor is how you tell two threads with the same person apart.

Inputs: no named parameters.

freelance_list_my_proposalsA

The bids this account has placed, and the invitations it has received. Requires READ_OWN. Status INVITED means a client pulled this account into a posting and nobody has bid yet.

Inputs: filter.

freelance_list_notificationsA

This account's own notification feed, newest first. Requires READ_OWN. The recipient is taken from the token and can never be passed in. side picks the lane and is effectively required - FIND_WORK is "things happening to my bids", HIRE_TALENT is "things happening to my requisitions" - because the two are different jobs and a merged feed answers neither.

Inputs: filter.

freelance_list_org_jobsA

Your own organization's job postings, in any status and including ORGANIZATION-visibility ones the public search never returns. Requires READ_OWN. This is the hiring side's list - use it to find the posting id you need before reading its proposals.

Inputs: filter.

freelance_list_proposals_for_jobA

Every bid on one of your organization's job postings - the hiring side's applicant list. Requires READ_OWN, and the posting must belong to your organization; asking about somebody else's requisition is refused, not filtered.

Inputs: jobPostingId (required).

freelance_refund_milestoneA

MOVES MONEY. Take escrowed money back out of a milestone and return it to the organization's spendable balance, while nothing has been handed over. Requires the SPEND scope, enforced by the server. Reversible - funding again restores it - which is why it carries no acknowledgement flag. It is still a decision about somebody's pay: confirm it before calling.

Inputs: id (required), milestoneId (required).

freelance_search_jobsA

Search open, publicly visible job postings across the whole marketplace - the work available to bid on. Requires READ_DIRECTORY. This is the FIND WORK side; for your own organization's requisitions in any status, including closed and organization-only ones, use freelance_list_org_jobs instead.

Inputs: filter.

freelance_search_talentA

Search the talent directory for listed freelancers - the people available to hire. Requires READ_DIRECTORY. Returns the public half of each profile only; contact details and verification documents are never in this projection. Omit filter entirely to see who is listed at all, then narrow: a search that returns nothing on the first try usually over-constrained city or skills.

Inputs: filter.

freelance_send_messageA

Send a message to a real person, under this account's name. Belongs to the MESSAGE scope. NOTHING UNDOES THIS - there is no edit and no delete, and the recipient is notified. Show the person you are acting for the exact wording and get a yes before calling; drafting a message is always fine, sending it is what waits. Address it EITHER with conversationId for an existing thread, OR with exactly one of jobPostingId / proposalId / contractId / freelanceProfileId, which finds or opens the thread anchored to that object.

Inputs: input (required).

freelance_submit_milestoneA

Hand a milestone in for review, moving it PENDING -> SUBMITTED. Freelancer lane: this account must be the contract's freelancer. It claims the work is done and puts the client on the spot, so do not call it on the freelancer's behalf without their say-so.

Inputs: id (required), milestoneId (required).

freelance_submit_proposalA

Bid on a job posting in this account's name. Belongs to the PROPOSE scope. THIS REACHES A REAL PERSON: the cover letter is read by the client as words this account wrote, so get the person you are acting for to approve the text and the rate before calling - never bid off your own reasoning about a good match. Read the posting with freelance_get_job first: if it carries applicantQuestions every one must be answered here, and if it carries acknowledgments you must send acknowledged: true, or the bid is refused.

Inputs: input (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 23 tools

    Disambiguation5/5

    Every tool targets a distinct resource-action pair: search/list tools are standard list-detail splits, and potentially overlapping tools like search_jobs vs list_org_jobs are explicitly separated by public vs own-organization visibility. No two tools do the same thing on the same resource.

    Naming Consistency5/5

    All tools follow a strict 'freelance_<verb>_<noun>' pattern in snake_case (e.g., search_jobs, fund_milestone, send_message). Compound nouns like my_profile or proposals_for_job are consistent and do not break the pattern.

    Tool Count3/5

    23 tools is within the borderline-heavy range, but the domain spans eight distinct areas (profiles, jobs, proposals, contracts, milestones, wallet, messaging, notifications). Each tool appears to earn its place, yet the count feels padded for a single server.

    Completeness3/5

    The core hire-to-payment lifecycle is covered, but there are notable gaps: no update or close/delete for job postings, no withdraw proposal, no cancel contract, and no edit milestone. These missing operations create dead ends that agents cannot work around.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI agents to Upwork's GraphQL API, enabling job discovery, proposal management, profile tracking, and analytics.
      10 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      F
      maintenance
      MCP server for the Upwork GraphQL API enabling job search, contract management, proposal drafting, and other Upwork automation tasks via natural language.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that connects AI coding assistants and agentic workflows to the Upwork freelance marketplace. Enables AI-powered job discovery, proposal generation, and contract management through a structured tool interface.
      MIT