{
  "markdown": "# Freelancer MCP Server\n\nAn [MCP](https://modelcontextprotocol.io) 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.\n\nSupports **multiple Freelancer accounts in one server** (e.g. your own account plus one or more clients' accounts you manage), switchable per tool call.\n\nThis 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.\n\n## Get your access token (do this first)\n\n1. Log in to Freelancer.com\n2. Go to **[accounts.freelancer.com/settings/develop](https://accounts.freelancer.com/settings/develop)**\n3. Under **Application Dashboard**, click **Generate Token**\n4. Copy the token shown under **Access Token**\n\n![Where to generate your Freelancer access token](assets/access-token.png)\n\nThat 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](#multiple-accounts)).\n\n## What you can ask Claude\n\n| Tool | Example prompt |\n|---|---|\n| `freelancer_list_accounts` | \"Which Freelancer accounts are connected?\" |\n| `freelancer_get_self` | \"Show my profile and reputation\" |\n| `freelancer_get_user` | \"Look up @some_freelancer on Freelancer\" |\n| `freelancer_search_projects` | \"Find the latest n8n automation projects under $500\" |\n| `freelancer_get_project` | \"Get details on project 12345678\" |\n| `freelancer_my_projects` | \"List my active projects\" / \"Show my completed projects\" |\n| `freelancer_get_project_bids` | \"Who has bid on project 12345 and how much?\" |\n| `freelancer_my_bids` | \"Show my awarded bids\" / \"Show my rejected bids\" |\n| `freelancer_place_bid` | \"Bid $200 on project 12345 with 5-day delivery\" |\n| `freelancer_get_milestones` | \"What milestones are on project 12345?\" |\n| `freelancer_list_threads` | \"Show my inbox\" |\n| `freelancer_get_messages` | \"Read this chat: freelancer.com/messages/thread/98765\" |\n| `freelancer_send_message` | \"Reply to thread 98765 saying...\" |\n| `freelancer_search_skills` / `list_skills` / `add_skills` / `remove_skills` / `set_skills` | \"Add n8n and Zapier to my skills\" |\n| `freelancer_list_profiles` / `create_profile` / `update_profile` | \"Create a specialty profile for AI automation\" |\n\nEvery tool accepts an optional `account` argument to pick which connected Freelancer account it should act on/as (see [Multiple accounts](#multiple-accounts)).\n\n### Analyzing past projects & winning strategy\n\nThere'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:\n\n> \"Pull my awarded bids and my rejected bids, then compare amount, delivery time, and proposal length/style to figure out what's working.\"\n\n> \"Look at my completed projects and tell me which skills show up most often.\"\n\n> \"Compare my bid on project X to the other bids on it — am I priced competitively?\"\n\nClaude 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.\n\n### Chat links and thread IDs\n\n`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.\n\n## See it in action\n\n**Finding and scoring the best projects to bid on, with a ready pitch script for each:**\n![Claude finding CRM projects worth bidding on, with per-project pitch scripts](assets/demo-find-jobs.jpeg)\n\n**Reading a client thread by chat link and building a conversion strategy:**\n![Claude reading a client message thread and giving a strategy to convert them](assets/demo-client-strategy.jpeg)\n\n**Auditing skills already on a profile:**\n![Claude listing all skills on a Freelancer profile, grouped by category](assets/demo-list-skills.jpeg)\n\n## Setup\n\nThe package is published on npm as [`freelancer-mcp-server`](https://www.npmjs.com/package/freelancer-mcp-server) — no clone, no build, `npx` fetches and runs it on demand.\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add freelancer --env FREELANCER_OAUTH_TOKEN=your_token_here -- npx -y freelancer-mcp-server\n```\n\nOr just ask Claude Code directly, in plain English, once you have your token:\n\n> \"Add the freelancer-mcp-server MCP server using npx, with my Freelancer access token set as FREELANCER_OAUTH_TOKEN\"\n\nClaude Code can run the `claude mcp add` command itself — you don't have to type it.\n\n### Claude Desktop\n\nOpen your Claude Desktop config file:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd this block inside `\"mcpServers\"` (create the file if it doesn't exist):\n\n```json\n{\n  \"mcpServers\": {\n    \"freelancer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"freelancer-mcp-server\"],\n      \"env\": {\n        \"FREELANCER_OAUTH_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop — you should see a 🔌 indicating the server connected.\n\n### Multiple accounts\n\nTo 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"freelancer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"freelancer-mcp-server\"],\n      \"env\": {\n        \"FREELANCER_ACCOUNTS\": \"{\\\"main\\\":\\\"token1\\\",\\\"client_acme\\\":\\\"token2\\\"}\"\n      }\n    }\n  }\n}\n```\n\nOr via `claude mcp add`:\n\n```bash\nclaude mcp add freelancer --env FREELANCER_ACCOUNTS='{\"main\":\"token1\",\"client_acme\":\"token2\"}' -- npx -y freelancer-mcp-server\n```\n\nThe 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.\n\n### Running from source (contributing)\n\n```bash\ngit clone https://github.com/godesigntech/freelancer-mcp-server.git\ncd freelancer-mcp-server\nnpm install\nnpm run build\nclaude mcp add freelancer --env FREELANCER_OAUTH_TOKEN=your_token_here -- node /FULL/PATH/TO/freelancer-mcp-server/dist/index.js\n```\n\n## Testing\n\nAsk Claude:\n> \"Show my Freelancer profile\"\n\nIf it responds with your username and stats, you're set.\n\n## Profile editing — what the Freelancer API actually allows\n\nThe Freelancer.com public REST API is read-mostly for profiles. After probing the live API, here's the real boundary:\n\n**Editable:**\n- ✅ 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.\n- ✅ 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.\n\n**NOT possible via the public API (web-UI only):**\n- ❌ Main account bio/tagline/hourly rate shown on your public page\n- ❌ Profile photo / avatar\n- ❌ Experience, education, publications, references, certifications\n- ❌ Portfolio (read-only via API)\n\n## Security notes\n\n- 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.\n- The server runs entirely on your machine; no telemetry, no third-party calls.\n- 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.\n- This repo contains no data from, and no dependency on, any other project — it's a clean, standalone Freelancer.com integration.\n\n## Troubleshooting\n\n**\"no Freelancer accounts configured\"**\n→ Set `FREELANCER_OAUTH_TOKEN` or `FREELANCER_ACCOUNTS` in your MCP client config.\n\n**401 Unauthorized**\n→ Token expired or wrong. Generate a fresh one at https://accounts.freelancer.com/settings/develop\n\n**\"Unknown account \"x\"\"**\n→ Run `freelancer_list_accounts` to see the exact labels configured, then use one of those.\n\n**Tool not appearing in Claude**\n→ 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.\n\n## Contributing\n\nIssues and PRs welcome. Keep changes scoped to the Freelancer.com API surface — this project intentionally stays a single-purpose, dependency-light MCP server.\n\n## License\n\nMIT\n",
  "bytes": 9174,
  "sha": "51bd0474bf88e6be721d992e897357f1f59cbb57293492113d99213230fb39bf",
  "repo_slug": "godesigntech/freelancer-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_godesigntech_freelancer_mcp_se_40a124a1/readme"
}