Skip to main content
Glama
Freelancer MCP Server

Freelancer MCP Server

by godesigntech

Freelancer MCP Server

An MCP server that connects Claude (Desktop, Code, or any MCP-compatible client) directly to Freelancer.com. Search and bid on projects, read and reply to client messages, review your track record, and manage skills/specialty profiles — all from a chat.

Supports multiple Freelancer accounts in one server (e.g. your own account plus one or more clients' accounts you manage), switchable per tool call.

This project is 100% self-contained: it talks only to freelancer.com's public API using whatever access token(s) you provide. No other data source, project, or third-party service is involved.

Get your access token (do this first)

  1. Log in to Freelancer.com

  2. Go to accounts.freelancer.com/settings/develop

  3. Under Application Dashboard, click Generate Token

  4. Copy the token shown under Access Token

Where to generate your Freelancer access token

That token is all this server needs — no password, no app review, no OAuth redirect flow. Repeat this for each additional Freelancer account you want connected (see Multiple accounts).

Related MCP server: Upwork MCP Server

What you can ask Claude

Tool

Example prompt

freelancer_list_accounts

"Which Freelancer accounts are connected?"

freelancer_get_self

"Show my profile and reputation"

freelancer_get_user

"Look up @some_freelancer on Freelancer"

freelancer_search_projects

"Find the latest n8n automation projects under $500"

freelancer_get_project

"Get details on project 12345678"

freelancer_my_projects

"List my active projects" / "Show my completed projects"

freelancer_get_project_bids

"Who has bid on project 12345 and how much?"

freelancer_my_bids

"Show my awarded bids" / "Show my rejected bids"

freelancer_place_bid

"Bid $200 on project 12345 with 5-day delivery"

freelancer_get_milestones

"What milestones are on project 12345?"

freelancer_list_threads

"Show my inbox"

freelancer_get_messages

"Read this chat: freelancer.com/messages/thread/98765"

freelancer_send_message

"Reply to thread 98765 saying..."

freelancer_search_skills / list_skills / add_skills / remove_skills / set_skills

"Add n8n and Zapier to my skills"

freelancer_list_profiles / create_profile / update_profile

"Create a specialty profile for AI automation"

Every tool accepts an optional account argument to pick which connected Freelancer account it should act on/as (see Multiple accounts).

Analyzing past projects & winning strategy

There's no single "analyze my strategy" button — instead, Claude does the analysis itself over the raw data this server exposes. This keeps the server a thin, honest API wrapper instead of a black box. Ask things like:

"Pull my awarded bids and my rejected bids, then compare amount, delivery time, and proposal length/style to figure out what's working."

"Look at my completed projects and tell me which skills show up most often."

"Compare my bid on project X to the other bids on it — am I priced competitively?"

Claude will chain freelancer_my_bids (status awarded vs rejected), freelancer_my_projects (status complete), and freelancer_get_project_bids to gather the data, then reason over it directly in the conversation.

freelancer_get_messages and freelancer_send_message accept either a plain numeric thread ID or a pasted Freelancer chat/message link — the server extracts the ID either way.

See it in action

Finding and scoring the best projects to bid on, with a ready pitch script for each: Claude finding CRM projects worth bidding on, with per-project pitch scripts

Reading a client thread by chat link and building a conversion strategy: Claude reading a client message thread and giving a strategy to convert them

Auditing skills already on a profile: Claude listing all skills on a Freelancer profile, grouped by category

Setup

The package is published on npm as freelancer-mcp-server — no clone, no build, npx fetches and runs it on demand.

Claude Code (CLI)

claude mcp add freelancer --env FREELANCER_OAUTH_TOKEN=your_token_here -- npx -y freelancer-mcp-server

Or just ask Claude Code directly, in plain English, once you have your token:

"Add the freelancer-mcp-server MCP server using npx, with my Freelancer access token set as FREELANCER_OAUTH_TOKEN"

Claude Code can run the claude mcp add command itself — you don't have to type it.

Claude Desktop

Open your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this block inside "mcpServers" (create the file if it doesn't exist):

{
  "mcpServers": {
    "freelancer": {
      "command": "npx",
      "args": ["-y", "freelancer-mcp-server"],
      "env": {
        "FREELANCER_OAUTH_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop — you should see a 🔌 indicating the server connected.

Multiple accounts

To connect more than one Freelancer account (your own plus, say, two clients'), use FREELANCER_ACCOUNTS instead of FREELANCER_OAUTH_TOKEN — a JSON object mapping a label you choose to each token:

{
  "mcpServers": {
    "freelancer": {
      "command": "npx",
      "args": ["-y", "freelancer-mcp-server"],
      "env": {
        "FREELANCER_ACCOUNTS": "{\"main\":\"token1\",\"client_acme\":\"token2\"}"
      }
    }
  }
}

Or via claude mcp add:

claude mcp add freelancer --env FREELANCER_ACCOUNTS='{"main":"token1","client_acme":"token2"}' -- npx -y freelancer-mcp-server

The first account listed becomes the default (used when a tool call omits account). Ask Claude "which Freelancer accounts are connected?" to confirm, then say e.g. "using the client_acme account, show me the latest projects" to target a specific one. Tokens are never logged, echoed back, or written anywhere by this server — they only ever go into the outgoing freelancer-oauth-v1 header.

Running from source (contributing)

git clone https://github.com/godesigntech/freelancer-mcp-server.git
cd freelancer-mcp-server
npm install
npm run build
claude mcp add freelancer --env FREELANCER_OAUTH_TOKEN=your_token_here -- node /FULL/PATH/TO/freelancer-mcp-server/dist/index.js

Testing

Ask Claude:

"Show my Freelancer profile"

If it responds with your username and stats, you're set.

Profile editing — what the Freelancer API actually allows

The Freelancer.com public REST API is read-mostly for profiles. After probing the live API, here's the real boundary:

Editable:

  • ✅ Skills/jobs — add, remove, or replace the skills on an account (/users/0.1/self/jobs). Freelancer caps the total number of skills per account.

  • ✅ Specialty profiles — create/update focused sub-profiles (/users/0.1/profiles): tagline, hourly_rate, description, skills. Caveats: the API has no endpoint to list your own profile IDs (you must already know them), and some account types (e.g. certain corporate accounts) cannot create new ones.

NOT possible via the public API (web-UI only):

  • ❌ Main account bio/tagline/hourly rate shown on your public page

  • ❌ Profile photo / avatar

  • ❌ Experience, education, publications, references, certifications

  • ❌ Portfolio (read-only via API)

Security notes

  • Tokens live only in your local MCP client config (or .env for npm run dev) — never committed, never sent anywhere but Freelancer's own API.

  • The server runs entirely on your machine; no telemetry, no third-party calls.

  • Destructive/real-world actions (place_bid, send_message, skill/profile edits) always surface for your review before they execute, since Claude shows tool calls before running them.

  • This repo contains no data from, and no dependency on, any other project — it's a clean, standalone Freelancer.com integration.

Troubleshooting

"no Freelancer accounts configured" → Set FREELANCER_OAUTH_TOKEN or FREELANCER_ACCOUNTS in your MCP client config.

401 Unauthorized → Token expired or wrong. Generate a fresh one at https://accounts.freelancer.com/settings/develop

"Unknown account "x"" → Run freelancer_list_accounts to see the exact labels configured, then use one of those.

Tool not appearing in Claude → If using npx, confirm Node.js 18+ is installed and npx -y freelancer-mcp-server runs without error from a terminal. If running from source, confirm the path in your config is the absolute path to dist/index.js, and that npm run build succeeded.

Contributing

Issues and PRs welcome. Keep changes scoped to the Freelancer.com API surface — this project intentionally stays a single-purpose, dependency-light MCP server.

License

MIT

Available Tools

21 tools
freelancer_add_skillsAdd SkillsA
Idempotent

Add one or more skills (jobs) to your Freelancer.com profile, keeping your existing skills.

Args:

  • skills (string[]): Skill names (e.g. "n8n", "Python") or numeric skill IDs. Names are resolved via the catalogue.

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: confirmation.

⚠️ This modifies your real profile. Note: Freelancer enforces a maximum number of skills per account; adding past the limit will be rejected by the API.

Use when: "Add n8n and Zapier to my skills", "Add skill 3112 to my profile"

Inputs: skills (required), account.

freelancer_create_profileCreate Specialty ProfileA

Create a new Freelancer.com "specialty profile" (a focused sub-profile, separate from your main account profile).

All fields are required by the API. Args:

  • profile_name (string): Internal name for the specialty profile

  • tagline (string): Short headline

  • hourly_rate (number): Hourly rate in USD

  • description (string): Profile description / bio

  • skills (string[], optional): Skill names or IDs for this profile

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: created profile (including its profile_id).

⚠️ Creates real data on your account. Freelancer caps the number of specialty profiles; some account types (e.g. certain corporate accounts) cannot create any and the API will reject with "reached the limit for creating new profiles".

Use when: "Create a specialty profile for AI automation"

Inputs: tagline (required), description (required), hourly_rate (required), profile_name (required), +2 more.

freelancer_get_messagesGet Thread MessagesA
Read-onlyIdempotent

Retrieve messages from a specific Freelancer.com thread.

Args:

  • thread_id (string | number): Thread ID, or a Freelancer.com chat/message link containing one (get the ID from freelancer_list_threads if unknown)

  • limit (number, 1-50, default 20): Number of messages

  • offset (number, default 0): Pagination offset

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: messages with text, sender, timestamp and attachment info

Use when: "Show messages in thread 12345", "What did the client say?", "Read the conversation", "Read this chat: https://www.freelancer.com/messages/thread/12345"

Inputs: thread_id (required), limit, offset, account.

freelancer_get_milestonesGet Project MilestonesA
Read-onlyIdempotent

List milestones for a specific Freelancer.com project.

Args:

  • project_id (number): The project ID

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: list of milestones with amount, description, status and dates

Milestone statuses include: created, requested, pending, released, cancelled

Use when: "What are the milestones on project 12345?", "Has the milestone been released?", "Check payment status"

Inputs: project_id (required), account.

freelancer_get_projectGet Project DetailsA
Read-onlyIdempotent

Get full details of a specific Freelancer.com project by ID.

Args:

  • project_id (number): The numeric project ID

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: full description, budget, status, skills, bid stats, timeline

Use when: "Tell me more about project 12345678", "Get the details for this project"

Inputs: project_id (required), account.

freelancer_get_project_bidsGet Project BidsA
Read-onlyIdempotent

List all bids on a specific Freelancer.com project.

Args:

  • project_id (number): The project ID to fetch bids for

  • limit (number, 1-50, default 10): Number of bids to return

  • offset (number, default 0): Pagination offset

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: list of bids with amount, period, bidder reputation and description

Use when: "Who has bid on project 12345?", "How much are people bidding?", "Show me the bids on my project"

Inputs: project_id (required), limit, offset, account.

freelancer_get_selfGet My ProfileA
Read-onlyIdempotent

Retrieve your own Freelancer.com profile, including reputation, earnings, skills, location and stats.

Args:

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns:

  • username, display name, tagline, location

  • reputation score and total reviews

  • registered skills/job categories

  • hourly rate and earnings

  • registration date

Use when: "What's my profile?", "Show my reputation", "What are my stats on Freelancer?"

Inputs: account.

freelancer_get_userGet User ProfileA
Read-onlyIdempotent

Retrieve a Freelancer.com user profile by username or user ID.

Args:

  • username (string, optional): Freelancer username (e.g. "usman_godesign")

  • user_id (number, optional): Numeric Freelancer user ID Provide at least one of username or user_id.

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: profile, reputation, skills, location, hourly rate

Use when: "Look up this freelancer", "What's their rating?", "Check the profile of user 12345"

Inputs: account, user_id, username.

freelancer_list_accountsList Configured AccountsA
Read-onlyIdempotent

List the Freelancer.com account labels configured on this MCP server (never the tokens themselves).

Use this to discover which account value to pass to other tools when multiple Freelancer profiles are connected (e.g. your own account plus one or more clients' accounts).

Returns: account labels, and which one is the default (used when a tool call omits account).

Use when: "Which Freelancer accounts are connected?", "Switch to the client2 account", "List my connected profiles"

Inputs: no named parameters.

freelancer_list_profilesList Specialty ProfilesA
Read-onlyIdempotent

Fetch one or more of your Freelancer.com "specialty profiles" by their numeric profile IDs.

Note: Freelancer's API has no endpoint that lists your profile IDs for you — you must already know the ID(s) (e.g. from the profile URL). This is a limitation of the public API, not this tool.

Args:

  • profile_ids (number[]): Numeric specialty-profile IDs to fetch.

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: profile details (name, tagline, hourly rate, description).

Use when: "Show specialty profile 12345"

Inputs: profile_ids (required), account.

freelancer_list_skillsList My SkillsA
Read-onlyIdempotent

List the skills (jobs) currently on your own Freelancer.com profile.

Returns: your skills with numeric ID, name and category.

Args:

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Use when: "What skills are on my profile?", "List my skills", "Do I have n8n listed?"

Inputs: account.

freelancer_list_threadsList Message ThreadsA
Read-onlyIdempotent

List your Freelancer.com inbox message threads.

Args:

  • context_type (string, optional): Filter by "project" or "freelancer_dashboard"

  • limit (number, 1-50, default 10): Number of threads

  • offset (number, default 0): Pagination offset

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: list of threads with members, last activity and message count

Use when: "Show my inbox", "List my message threads", "Who has messaged me?"

Inputs: limit, offset, account, context_type.

freelancer_my_bidsList My BidsA
Read-onlyIdempotent

List bids you have placed on Freelancer.com projects.

Args:

  • status (string, optional): Filter by bid status — "active", "awarded", "revoked", "rejected"

  • limit (number, 1-50, default 10): Number of bids to return

  • offset (number, default 0): Pagination offset

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: your bids with project info, amounts and status. To analyze your winning strategy, call this twice — once with status "awarded" and once with status "rejected" — and compare amount, period and proposal style across the two sets yourself.

Use when: "Show my bids", "Which of my bids are active?", "Have any of my bids been awarded?", "What's my win rate?", "Analyze my winning bids vs rejected ones"

Inputs: limit, offset, status, account.

freelancer_my_projectsList My ProjectsA
Read-onlyIdempotent

List projects you own or are working on as a freelancer.

Args:

  • role (string): "owner" (projects you posted) or "freelancer" (projects you're hired on)

  • status (string, optional): "active", "complete", "closed"

  • limit (number, 1-50, default 10): Number of results

  • offset (number, default 0): Pagination offset

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: list of your projects with status, budget and progress. To analyze past performance ("what are my winning strategies?"), call this with status "complete" and pair it with freelancer_my_bids (status "awarded") — reason over the combined results yourself (skills used, budget ranges, proposal style).

Use when: "Show my active projects", "List projects I'm working on", "What projects have I posted?", "Analyze my past completed projects"

Inputs: role, limit, offset, status, +1 more.

freelancer_place_bidPlace a BidA

Submit a bid / proposal on a Freelancer.com project.

Args:

  • project_id (number): Project ID to bid on

  • amount (number): Your bid amount in the project's currency

  • period (number): Delivery time in days

  • description (string): Your proposal text (cover letter)

  • milestone_percentage (number, 0-100, default 100): Percentage to request as initial milestone

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account. This is the account the bid is placed FROM.

Returns: confirmation with bid ID and status

⚠️ This creates a real bid on your account. Review before confirming — including which account, when multiple are configured.

Use when: "Bid $150 on project 12345 with 7 days delivery", "Submit a proposal"

Inputs: amount (required), period (required), project_id (required), description (required), +2 more.

freelancer_remove_skillsRemove SkillsA
DestructiveIdempotent

Remove one or more skills (jobs) from your Freelancer.com profile.

Args:

  • skills (string[]): Skill names or numeric IDs to remove.

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: confirmation.

⚠️ This modifies your real profile.

Use when: "Remove PHP from my skills", "Drop skill 3 from my profile"

Inputs: skills (required), account.

freelancer_search_projectsSearch ProjectsA
Read-onlyIdempotent

Search for projects/jobs on Freelancer.com by keyword, budget or project type.

Args:

  • query (string, optional): Search keywords (e.g. "wordpress website", "n8n automation")

  • project_type (string, optional): "fixed" or "hourly"

  • min_budget (number, optional): Minimum budget in USD

  • max_budget (number, optional): Maximum budget in USD

  • limit (number, 1-50, default 10): Number of results

  • offset (number, default 0): Pagination offset

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: list of matching projects with title, budget, bid count, skills required. Results are ordered newest-first, so this also answers "what are the latest projects?".

Use when: "Find projects for Zoho CRM", "Show me hourly WordPress jobs", "Any SEO projects available?", "What are the latest projects posted?"

Inputs: limit, query, offset, account, +3 more.

freelancer_search_skillsSearch SkillsA
Read-onlyIdempotent

Search the Freelancer.com skill (job) catalogue by name. Use this to find the numeric skill IDs needed by the skill-management tools.

Args:

  • query (string): Substring to match against skill names (case-insensitive), e.g. "python", "n8n", "automation"

  • limit (number, default 25): Max results

Returns: matching skills with their numeric ID, name and category.

Use when: "Find the skill ID for n8n", "What automation skills exist?", "Search skills for react"

Inputs: query (required), limit.

freelancer_send_messageSend MessageA

Send a message in an existing Freelancer.com thread.

Args:

  • thread_id (string | number): The thread ID to reply to, or a Freelancer.com chat link containing one

  • message (string): Your message text

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account. This is the account the message is sent FROM.

Returns: confirmation with message ID

⚠️ This sends a real message from your account.

Use when: "Reply to thread 12345 saying...", "Message the client", "Send a follow-up"

Inputs: message (required), thread_id (required), account.

freelancer_set_skillsSet Skills (Replace All)A
DestructiveIdempotent

Replace your ENTIRE skill list with the provided skills. Any current skill not in the list is removed.

Args:

  • skills (string[]): The complete set of skill names or numeric IDs your profile should have.

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: confirmation.

⚠️ Destructive: this overwrites all existing skills. Consider freelancer_list_skills first, and freelancer_add_skills if you only want to append.

Use when: "Set my skills to exactly Python, n8n and React", "Replace all my skills with this list"

Inputs: skills (required), account.

freelancer_update_profileUpdate Specialty ProfileA
Idempotent

Update fields on one of your Freelancer.com "specialty profiles". Only the fields you supply are changed.

Important: this edits a SPECIALTY profile identified by profile_id — it does NOT edit your main account profile (description/tagline/hourly rate shown on your public freelancer page). Freelancer's public API exposes no endpoint to edit the main profile; that is web-UI-only.

Args:

  • profile_id (number): The specialty profile's numeric ID (you must already know it)

  • tagline (string, optional)

  • hourly_rate (number, optional): USD

  • description (string, optional)

  • skills (string[], optional): Skill names or IDs (replaces this profile's skills)

  • account (string, optional): Which configured Freelancer account to use (see freelancer_list_accounts for labels). Omit to use your default/only account.

Returns: confirmation.

⚠️ Modifies real data. The API enforces ownership: editing a profile_id you don't own is rejected.

Use when: "Update specialty profile 12345's hourly rate to 40"

Inputs: profile_id (required), skills, account, tagline, +2 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose. Overlapping areas like my_bids vs get_project_bids or list_profiles vs get_self are well-differentiated by their descriptions and context, so an agent can easily select the correct one.

    Naming Consistency4/5

    All tools follow a consistent verb_noun pattern with a 'freelancer_' prefix. The use of 'my_' for my_bids and my_projects is a slight deviation from the 'list_' convention but still readable and predictable.

    Tool Count4/5

    21 tools is on the high end of what is appropriate for a Freelancer platform, but each tool addresses a distinct need (skills, projects, bids, messages, profiles, search). The count is justified by the domain's complexity.

    Completeness4/5

    The tool set covers the major workflows: searching projects, bidding, managing skills and profiles, messaging, and tracking projects. Missing are tools for withdrawing bids, deleting messages, or editing the main profile (API limitation), but these are acceptable gaps.

    Related MCP Connectors

    Related MCP Servers