Freelancer MCP Server
Allows searching and bidding on Freelancer.com projects, managing skills and specialty profiles, reading and replying to client messages, and reviewing track record, all through the Freelancer.com public API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Freelancer MCP Server Find Python web scraping projects under $300"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
Log in to Freelancer.com
Under Application Dashboard, click Generate Token
Copy the token shown under 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 |
| "Which Freelancer accounts are connected?" |
| "Show my profile and reputation" |
| "Look up @some_freelancer on Freelancer" |
| "Find the latest n8n automation projects under $500" |
| "Get details on project 12345678" |
| "List my active projects" / "Show my completed projects" |
| "Who has bid on project 12345 and how much?" |
| "Show my awarded bids" / "Show my rejected bids" |
| "Bid $200 on project 12345 with 5-day delivery" |
| "What milestones are on project 12345?" |
| "Show my inbox" |
| "Read this chat: freelancer.com/messages/thread/98765" |
| "Reply to thread 98765 saying..." |
| "Add n8n and Zapier to my skills" |
| "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.
Chat links and thread IDs
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:

Reading a client thread by chat link and building a conversion strategy:

Auditing skills already on a profile:

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-serverOr 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.jsonWindows:
%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-serverThe 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.jsTesting
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
.envfornpm 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 toolsfreelancer_add_skillsAdd SkillsAIdempotent
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 MessagesARead-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 MilestonesARead-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 DetailsARead-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 BidsARead-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 ProfileARead-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 ProfileARead-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 AccountsARead-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 ProfilesARead-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 SkillsARead-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 ThreadsARead-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 BidsARead-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 ProjectsARead-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 SkillsADestructiveIdempotent
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 ProjectsARead-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 SkillsARead-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)ADestructiveIdempotent
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 ProfileAIdempotent
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
Scored across 21 tools
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.
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.
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.
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
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Create contacts, move deals, send proposals and invoices, read your inbox, from Claude or ChatGPT.
Connect Claude to Fathom meeting recordings, transcripts, and summaries
Related MCP Servers
- AlicenseAqualityFmaintenanceConnects Claude to Jobber to manage clients, jobs, invoices, quotes, and scheduling through natural language.10MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with the Upwork freelance marketplace, including job search, proposal management, contract tracking, and earnings monitoring.261MIT
- AlicenseAqualityDmaintenanceEnables Claude to search jobs, manage proposals, messages, and contracts on Upwork via browser automation.18Apache 2.0
- AlicenseNot gradedqualityDmaintenanceConnects Claude to Frame.io to pull transcripts, post frame-accurate comments, list comments, and upload attachments.MIT