The MCP server dev.cotlet/peopleperhour supports searching for PeoplePerHour projects, freelancers, and Offers. It also retrieves and reads briefs and profiles to provide relevant information from the PeoplePerHour platform for developer workflows.
🛠️ Key Features
Search projects on PeoplePerHour
Search freelancers on PeoplePerHour
Search Offers on PeoplePerHour
Read briefs
Read profiles
🚀 Use Cases
Finding PeoplePerHour projects to reference for work
Browsing PeoplePerHour freelancer profiles
Reviewing PeoplePerHour offers for available services
Reading briefs and profiles to understand requirements and context
The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.
The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, not enabled for agents), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.
Parameters1
app
string
optional
Only this app, e.g. skool.
Raw schema
{
"type": "object",
"properties": {
"app": {
"type": "string",
"description": "Only this app, e.g. skool."
}
},
"additionalProperties": false
}
cotlet_request_apps
Requests access to apps for the user's workspace, as Request access in the console: a live app is granted at once, any other goes to the Cotlet team, who answer within 72 hours. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.
Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.
Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.
Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.
Parameters7
kind
string
required
bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.
title
string
required
One line, e.g. 'skool_list_members stops after 50 members'.
description
string
required
What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.
app
any
optional
App slug the report is about, e.g. 'skool'.
tool
any
optional
Tool or endpoint name, e.g. 'skool_list_members'.
call_id
any
optional
call_id of the call that went wrong, if any.
client
any
optional
Agent or tool sending this, e.g. 'Claude Code'.
Raw schema
{
"type": "object",
"properties": {
"kind": {
"description": "bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.",
"enum": [
"bug",
"error",
"feature_request",
"missing_feature",
"other"
],
"title": "Kind",
"type": "string"
},
"title": {
"description": "One line, e.g. 'skool_list_members stops after 50 members'.",
"maxLength": 200,
"minLength": 3,
"title": "Title",
"type": "string"
},
"description": {
"description": "What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.",
"maxLength": 5000,
"minLength": 10,
"title": "Description",
"type": "string"
},
"app": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "App slug the report is about, e.g. 'skool'.",
"title": "App"
},
"tool": {
"anyOf": [
{
"maxLength": 160,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tool or endpoint name, e.g. 'skool_list_members'.",
"title": "Tool"
},
"call_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "call_id of the call that went wrong, if any.",
"title": "Call Id"
},
"client": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Agent or tool sending this, e.g. 'Claude Code'.",
"title": "Client"
}
},
"required": [
"kind",
"title",
"description"
],
"additionalProperties": false,
"description": "Body of POST /api/v1/reports and the arguments of the MCP tool cotlet_report_issue.",
"title": "AgentReportCreate"
}
cotlet_browser_connect
Wakes the user's Cloud Browser of one app (a real Chrome on Cotlet, signed in to that app as the user) and returns cdp_url, a Chrome DevTools Protocol WebSocket that gives a CDP client full control of the browser. It works in one open tab, the app's: the user watches it live, and new tabs are refused. Every started minute of an open connection costs credits. Needs the user's Cotlet API key or sign-in.
Open Chrome DevTools connections to the user's Cloud Browsers with the minutes and credits each has cost so far, and the cdp_url links still valid. With close: true it ends the open connections and takes back the unused links, of one app or of all. Needs the user's Cotlet API key or sign-in.
Parameters1
close
boolean
optional
End the connections and revoke the links.
Raw schema
{
"type": "object",
"properties": {
"close": {
"type": "boolean",
"description": "End the connections and revoke the links."
}
},
"additionalProperties": false
}
cotlet_browser_open
Wakes the user's own browser on Cotlet, a real Chrome hosted for them: their web browser with the sites they signed in to there, or with `app` that app's browser, signed in to the app. Opens `url` when given and returns the page's URL and title. The user watches every step live. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
url
string
optional
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"additionalProperties": false
}
cotlet_browser_navigate
Opens a public http or https address in the user's browser on Cotlet and returns the URL and title it ended on. An app's browser opens only that app's pages. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
url
string
required
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"required": [
"url"
],
"additionalProperties": false
}
cotlet_browser_read
Returns the current page of the user's browser on Cotlet: its readable text, up to 20,000 characters, and a numbered list of its links, buttons and fields. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Returns a JPEG image of the visible part of the current page in the user's browser on Cotlet, with its URL and title: boards, canvases and layouts that the page text does not show. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Scrolls the current page in the user's browser on Cotlet with the mouse wheel, as a person does: down or up by `screens` viewport heights (default 0.8), to the top or the bottom, or until element `element` is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters3
direction
string
optional
Where to scroll. Default: down.
screens
number
optional
How far, in viewport heights, for down and up. Default: 0.8.
element
integer
optional
Scroll until this element of the element list is in view.
Raw schema
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"enum": [
"down",
"up",
"top",
"bottom"
],
"description": "Where to scroll. Default: down."
},
"screens": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 10,
"description": "How far, in viewport heights, for down and up. Default: 0.8."
},
"element": {
"type": "integer",
"minimum": 1,
"description": "Scroll until this element of the element list is in view."
}
},
"additionalProperties": false
}
cotlet_browser_click
Clicks a link, button or other element of the current page in the user's browser on Cotlet, by its number in the page's element list, and returns the URL and title after the click. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
element
integer
required
The element's number in the element list of the current page.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
}
},
"required": [
"element"
],
"additionalProperties": false
}
cotlet_browser_type
Types text into a field of the current page in the user's browser on Cotlet, by the field's number in the page's element list, and with `submit` presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters3
element
integer
required
The element's number in the element list of the current page.
text
string
required
The text to type.
submit
boolean
optional
Press Enter after typing, e.g. to search.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"text": {
"type": "string",
"maxLength": 5000,
"description": "The text to type."
},
"submit": {
"type": "boolean",
"description": "Press Enter after typing, e.g. to search."
}
},
"required": [
"element",
"text"
],
"additionalProperties": false
}
cotlet_browser_select
Chooses an option of a drop-down list on the current page in the user's browser on Cotlet, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
option
string
required
The option.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"option": {
"type": "string",
"maxLength": 300,
"description": "The option."
}
},
"required": [
"element",
"option"
],
"additionalProperties": false
}
cotlet_browser_press
Presses one key on the current page in the user's browser on Cotlet, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list. Returns the URL and title after it. Enter on account pages is refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Puts files into a file field of the current page in the user's browser on Cotlet, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
files
array
required
The files.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public file URL."
},
"file_id": {
"type": "string",
"description": "A file uploaded to Cotlet."
}
},
"additionalProperties": false
},
"description": "The files."
}
},
"required": [
"element",
"files"
],
"additionalProperties": false
}
cotlet_browser_close
Ends the session in the user's browser on Cotlet (with `app`, that app's browser): the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.
PeoplePerHour API and MCP server: connect PeoplePerHour to ChatGPT and Claude
Yes, ChatGPT, Claude and other AI agents can work in your PeoplePerHour account. That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI searches new projects, reads the briefs and files, shortlists the ones worth a proposal, drafts the proposal for you and compares freelancers. It shows you what it will do first and sends nothing to other people until you say so.
As of November 2026, this repo is the missing piece: 17 PeoplePerHour tools for AI assistants and scripts.
What you can ask
Check PeoplePerHour for web design projects posted since yesterday, skip anything under £200 or with more than 15 proposals, read the briefs of the rest and give me a shortlist of five.
Read the brief of project 4527712, open the files the buyer attached, list what I must deliver and the questions I have to answer, and draft a proposal I can paste.
Is project 4527712 still open, and how many proposals does it have now?
Find logo designers rated 80% or more at £10 to £30 an hour, read the profiles and recent reviews of the top five, and tell me which three to contact.
Save a search for urgent fixed-price design projects called "Urgent design" with a daily email.
A PeoplePerHour API and a PeoplePerHour MCP server you run on your own computer, in Python, on the session of your own Google Chrome. The same 17 PeoplePerHour tools we run in production at Cotlet: search open projects and read full briefs, search freelancers and Offers and read profiles with recent reviews, keep a project watchlist and saved searches with email alerts, see median budgets per category, and read your own posted projects, notifications and WorkStreams.
PeoplePerHour has no public API and no official MCP server. This repo gives you both:
MCP server for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. Setup
REST API on http://127.0.0.1:8787/api/v1/peopleperhour, with OpenAPI docs at /docs. Setup
Python: call("search_projects", query="web design"), plus 9 ready scripts in examples/.
13 tools read. The other 4 change only your own watchlist and saved searches. Nothing here sends a proposal or a message, posts a project, buys an Offer or pays, and no Proposal credit is spent.
Free for your own use, your own business included (license).
Does PeoplePerHour have an API?
No. PeoplePerHour has no public API, no developer docs and no webhooks (checked 12 Oct 2026). The one built-in alert is Saved Searches: up to 10 searches on the Jobs page, each emailing new results instantly or once a day. PeoplePerHour gives you nothing to call them from code; here save_search and list_saved_searches manage them. This repo and Cotlet give you 17 PeoplePerHour tools as a REST API and an MCP server.
Can I get a PeoplePerHour API key?
Not from PeoplePerHour for your own account. With Cotlet you get your own API key that works with your PeoplePerHour account, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own PeoplePerHour session.
Is there an official ChatGPT integration for PeoplePerHour?
No. PeoplePerHour has no official ChatGPT or Claude connector. Cotlet is an unofficial one that works today, in the ChatGPT and Claude apps and in any AI agent that takes an MCP server.
How do I connect PeoplePerHour to ChatGPT?
Sign up at cotlet.dev, sign in to PeoplePerHour once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your PeoplePerHour like you would ask an assistant. ChatGPT needs a server on the internet, so this repo alone, running on your computer, does not connect to ChatGPT.
Can ChatGPT find PeoplePerHour projects for me?
Yes, with Cotlet. It searches new projects by your skills and budget, skips the crowded ones, reads the briefs and attached files, and drafts a proposal you paste yourself. It never sends a proposal or spends your credits.
Can I automate PeoplePerHour with Zapier, Make or n8n?
PeoplePerHour has no Zapier or Make app. With Cotlet, n8n, Make and Zapier can search projects and freelancers and send you a daily shortlist.
Can I use it from my phone?
Yes, with Cotlet: once it is set up, the ChatGPT and Claude apps on your phone can use PeoplePerHour for you.
Do I need to be technical?
For Cotlet, no: you sign in to PeoplePerHour and add Cotlet to ChatGPT or Claude, with step-by-step instructions in your account. This repo is for people who are fine with Python and a terminal.
Is my PeoplePerHour account safe?
Yes. Neither Cotlet nor this repo sees or stores your PeoplePerHour password. You sign in yourself, the way you always do, and the AI works on that signed-in session. Anything that reaches other people asks for your OK first: in Cotlet by default, here through your MCP client.
Is it free?
This repo is free, also in your own business. Cotlet is free for 7 days with no card, then one-time credit packs from $29, no subscription. Pricing.
I manage PeoplePerHour for several accounts or clients. Does that work?
Yes, with Cotlet. Each PeoplePerHour login gets its own connection. Write to contact@cotlet.dev and tell us how many accounts you manage.
How it works
text
AI agent (MCP) / script (REST, Python) ──▶ peopleperhour-mcp on your computer ──your cookies──▶ www.peopleperhour.com
▲
peopleperhour-mcp connect ────┘ reads them once from your Chrome (DevTools Protocol)
You sign in to PeoplePerHour in your own Chrome, the way you always do. Tick Remember me.
peopleperhour-mcp connect attaches to that Chrome through the Chrome DevTools Protocol, reads the peopleperhour.com cookies and saves them to ~/.config/peopleperhour-api-mcp/session.json, readable by your user only. It never sees or stores your password.
Every tool call is a request to the JSON API the PeoplePerHour site itself calls (www.peopleperhour.com/v2/...) with those cookies, sent with curl_cffi, which copies Chrome's TLS fingerprint. No headless browser runs.
The session lives in the api cookie, about 100 days after a sign-in with Remember me. When PeoplePerHour signs you out, the server reads the cookies from Chrome again, if Chrome is open with remote debugging on.
Requirements
Python 3.11 or newer.
Google Chrome 144 or newer, signed in to PeoplePerHour. Any Chrome or Chromium works with a debugging port.
macOS, Linux or Windows.
Any PeoplePerHour account. A free buyer account is enough for all 17 tools.
With uv: uv venv && uv pip install -e ., then uv run peopleperhour-mcp ....
Setting it up with an AI agent (Claude Code, Codex, Cursor)? Open it in this folder and ask it to set up the repo: AGENTS.md tells it every step, and it asks you only for the steps in Chrome.
To update: uv tool upgrade peopleperhour-api-mcp (or pip install -U peopleperhour-api-mcp), from source git pull && pip install -e .. We copy every change of the hosted PeoplePerHour tools into this repo.
Connect your Chrome
Option A: your everyday Chrome (recommended)
Open chrome://inspect/#remote-debugging in Chrome and switch remote debugging on. Chrome then accepts DevTools connections from programs on this computer, and asks you before each one.
Chrome asks whether to allow the connection. Click Allow.
text
Saved 9 PeoplePerHour cookies to /Users/you/.config/peopleperhour-api-mcp/session.json
Signed in to PeoplePerHour as Maya Reed (maya@yourname.com)
You can switch remote debugging off again afterwards. Leave it on if you want the server to pick up a new session by itself after PeoplePerHour signs you out.
connect looks for Chrome's DevToolsActivePort file in the default profile folder. For Chrome Beta, Canary or a custom profile folder, pass --profile-dir "<folder>".
Option B: a Chrome with a debugging port
Chrome does not open a debugging port on your default profile, so start a separate one, sign in to PeoplePerHour there once, and connect to it:
--cdp also takes a ws:// DevTools URL, for example of a Chrome on another machine reached over an SSH tunnel.
Option C: paste the cookie by hand
For a server with no Chrome: in Chrome open DevTools on peopleperhour.com, Application > Cookies > https://www.peopleperhour.com, copy the value of api, then:
bash
peopleperhour-mcp connect --token # paste it, input is hidden# or, without a session file:export PEOPLEPERHOUR_AUTH_TOKEN=...
A pasted token is not refreshed on its own. Paste a new one when PeoplePerHour signs you out.
Check the session at any time:
bash
peopleperhour-mcp status
MCP server
The MCP server lists all 17 tools with their input schemas and a description written for agents. The 13 read tools are marked read-only; --read-only hides the 4 that change your watchlist and saved searches.
Claude Code
bash
claude mcp add peopleperhour -- uvx peopleperhour-api-mcp mcp
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
peopleperhour-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:
bash
peopleperhour-mcp serve
claude mcp add --transport http peopleperhour http://127.0.0.1:8787/mcp
Then ask your agent things like:
Check PeoplePerHour for web design projects posted since yesterday, skip anything under £200 or with more than 15 proposals, read the briefs of the rest and give me a shortlist of five.
Read the brief of project 4527712, open the files the buyer attached, list what I must deliver and the questions I have to answer, and draft a proposal I can paste.
Is project 4527712 still open, and how many proposals does it have now?
Find logo designers rated 80% or more at £10 to £30 an hour, read the profiles and recent reviews of the top five, and tell me which three to contact.
Save a search for urgent fixed-price design projects called "Urgent design" with a daily email.
REST API
bash
peopleperhour-mcp serve # http://127.0.0.1:8787, MCP at /mcp, docs at /docs
Each tool has its own route under /api/v1/peopleperhour, the same paths as the hosted API at cotlet.dev, so code written against one works with the other. Path parts and the query string are arguments.
bash
curl 'http://127.0.0.1:8787/api/v1/peopleperhour/projects/search?query=web%20design&since=2026-10-21T07:00:00Z&limit=20'
curl 'http://127.0.0.1:8787/api/v1/peopleperhour/projects/4527712'
curl 'http://127.0.0.1:8787/api/v1/peopleperhour/freelancers/search?query=logo%20design&min_rating=80'
curl -X PUT 'http://127.0.0.1:8787/api/v1/peopleperhour/projects/4527712/watch'
Any tool by name, body as its arguments:
bash
curl -X POST http://127.0.0.1:8787/api/v1/peopleperhour/tools/search_projects -d '{"category": "design", "limit": 10}'
GET /api/v1/peopleperhour/tools: every tool with its route, input schema and an example answer.
GET /docs: interactive OpenAPI docs, GET /openapi.json the schema, for n8n, Postman or a generated client.
Answers are JSON. List tools return next_cursor; pass it back as cursor for the next page.
The server listens on 127.0.0.1 only. To reach it from another device of yours, set a token, and every request then needs Authorization: Bearer <token>:
New projects for one or more keywords in the last N hours, merged, cut on --min-budget (or --hourly-rate) and --max-proposals, then the full brief, questions and files of each one left.
On a schedule, cron on your own computer works while it is on: 0 * * * * cd ~/peopleperhour-api-mcp-server && .venv/bin/python examples/watch_urgent_projects.py --category design --state urgent.json.
Budgets are compared as PeoplePerHour gives them, in the buyer's currency (GBP, EUR or USD), so a floor of 200 means 200 of whatever the buyer picked.
All 17 tools
peopleperhour-mcp tools prints this list, peopleperhour-mcp tools --json adds the input schemas. Times are UTC.
Projects
Tool
Access
REST route
What it does
search_projects
read
GET /projects/search
Open projects buyers posted, newest first, with budget, category, proposals and the brief's start.
get_project
read
GET /projects/{project_id}
One project's full brief with budget, attachments, interview questions, buyer and proposal count.
list_my_projects
read
GET /projects/mine
Projects this account posted as a buyer, with status, budget and proposal count.
Watchlist
Tool
Access
REST route
What it does
watch_project
write
PUT /projects/{project_id}/watch
Add a project to this account's watchlist (Favourite Jobs) to come back to it later.
unwatch_project
write
DELETE /projects/{project_id}/watch
Take a project off this account's watchlist.
list_watchlist
read
GET /projects/watched
Open projects on this account's watchlist (Favourite Jobs), with budget and proposal count.
Saved searches
Tool
Access
REST route
What it does
list_saved_searches
read
GET /saved-searches
This account's saved project searches with their filters and email alert setting.
save_search
write
POST /saved-searches
Save a project search with an email alert, or rename one or change how often it emails.
delete_saved_search
write
DELETE /saved-searches/{saved_search_id}
Delete one of this account's saved project searches and its email alert.
Freelancers
Tool
Access
REST route
What it does
search_freelancers
read
GET /freelancers/search
Freelancers by skill or keyword, with rate, rating, reviews, completed projects and skills.
get_freelancer
read
GET /freelancers/{freelancer_id}
A freelancer's public profile: rate, stats, skills, portfolio and the latest reviews on the page.
Offers
Tool
Access
REST route
What it does
search_offers
read
GET /offers/search
Fixed-price Offers freelancers sell, by keyword or price, with sales, rating and seller.
get_offer
read
GET /offers/{offer_id}
One Offer with its full description, what the seller needs from you, prices, add-ons and images.
Account, notifications and WorkStreams
Tool
Access
REST route
What it does
get_account
read
GET /account
The signed-in PeoplePerHour account: name, type, buyer stats, unread messages and favourite counts.
list_notifications
read
GET /notifications
The latest notifications of this account (proposals, messages, project updates) and unread counts.
list_workstreams
read
GET /workstreams
This account's WorkStreams (conversations with hired freelancers) with the last message.
Categories
Tool
Access
REST route
What it does
list_categories
read
GET /categories
The 10 project categories with their subcategories and typical budgets per freelancer level.
since makes polling cheap: an agent passes the time of its last check and reads only what arrived after it. One call with since scans at most the 200 newest projects, so a page can hold fewer than limit and still have a next_cursor.
Budgets, rates and prices come as PeoplePerHour gives them: a project in the buyer's currency, freelancer rates, Offers and median budgets in your account currency or the one you pick.
Not in this version: the freelancer side (proposals, your seller profile, your own Offers), posting or editing projects, sending messages in WorkStreams, accepting proposals, and payments, invoices and Proposal credits.
Never built, on purpose: your PeoplePerHour sign-in, email, password and settings, and anything that moves money (Proposal credits, subscriptions, payments). Every request passes a guard that refuses any change to those PeoplePerHour paths.
Configuration
Variable
Default
What it does
PEOPLEPERHOUR_MCP_HOME
~/.config/peopleperhour-api-mcp
Folder of session.json.
PEOPLEPERHOUR_AUTH_TOKEN
PeoplePerHour api cookie, instead of peopleperhour-mcp connect.
PEOPLEPERHOUR_PROXY
Proxy for every request to PeoplePerHour, e.g. http://user:pass@host:port.
PEOPLEPERHOUR_MCP_READ_ONLY
1 hides and refuses the 4 tools that change PeoplePerHour: watchlist and saved searches (same as --read-only).
PEOPLEPERHOUR_MCP_TOKEN
Bearer token required by serve; needed to listen beyond 127.0.0.1.
PEOPLEPERHOUR_MCP_HOST, PEOPLEPERHOUR_MCP_PORT
127.0.0.1, 8787
Address of serve.
Security and your PeoplePerHour account
Your password never reaches this code. Only cookies are read, and only those of peopleperhour.com.
The session file is yours.session.json is created with mode 0600. Anyone who has it can act as you on PeoplePerHour, so keep it out of git and shared folders.
Local by default.serve binds to 127.0.0.1 and refuses another address without PEOPLEPERHOUR_MCP_TOKEN.
peopleperhour.com only. Requests and redirects outside peopleperhour.com are refused. Attachment links point to PeoplePerHour's file host; the server returns them and does not download them.
Your own lists only. 13 tools read. The 4 writes change your watchlist and saved searches and nothing else: no proposal, message or Offer purchase goes to anyone. A watched project lists you among its watchers, so unwatch what you no longer follow.
Keep the pace human. A cron job every hour is fine. Hundreds of calls a minute is not how a person browses, and you are responsible for what runs in your account.
Errors
The REST API answers {"error": "<code>", "message": "..."}. The MCP server returns the same code and message as a tool error.
Status
Code
What to do
401
auth_required, auth_expired
No session, or PeoplePerHour signed you out. Sign in to PeoplePerHour in Chrome and run peopleperhour-mcp connect.
403
target_blocked
PeoplePerHour refused the request or showed a bot check. Open peopleperhour.com in Chrome once, then retry.
409
captcha_required
PeoplePerHour asks for a CAPTCHA. Solve it in Chrome.
422
invalid_input
An argument is missing or wrong; the message names it.
429
rate_limited
PeoplePerHour is limiting the account. Wait a few minutes.
502
target_error
No such project, freelancer, Offer or saved search, a private or removed one, a filter PeoplePerHour refused (the message gives its reason), or PeoplePerHour answered with an error or changed its site. git pull for the latest tools, or open an issue.
your own Cloud Browser in the EU, profile encrypted with AES-256-GCM
When PeoplePerHour changes its site
git pull once we have fixed it
fixed for you, every tool tested daily
Works with
MCP clients on your machine, local scripts
Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client
Who may use it
you and your own business
you, teams, businesses, agencies
Price
free
free 7-day trial with 2,000 credits, no card; then one-time packs from $29 for 5,000 credits
On the hosted version a successful call uses 10 credits for most tools, failed calls are free, and the Cloud Browser uses 50 credits a day while it has an app enabled for agents. Full pricing.
FAQ
Is there a PeoplePerHour MCP server for Claude, ChatGPT or Cursor?
Yes, this one runs on your machine: peopleperhour-mcp mcp for Claude Code, Claude Desktop, Cursor and Codex. ChatGPT and Claude.ai connectors need a public HTTPS URL, which the hosted PeoplePerHour MCP server gives you.
Is this a PeoplePerHour scraper?
It returns what people want a job scraper for (new projects with budget, proposals and brief, freelancers and Offers, as JSON or CSV) but runs no headless browser. It calls the same JSON endpoints the PeoplePerHour site calls, in your own account. The one HTML page it reads is a freelancer's profile, for the latest reviews.
Can I get new PeoplePerHour projects as they are posted?
Yes. Call search_projects with since set to your last check, from cron or an agent. watch_urgent_projects.py keeps that time in a state file for you.
Can it send proposals or answer buyers?
No. Proposals, WorkStream messages, buying Offers, invoices and your Proposal credits are not in this version, and it spends no credits. It can read your WorkStreams and notifications. You write and send proposals and messages on PeoplePerHour yourself.
Can I hire on PeoplePerHour with it?
It helps you choose: search_freelancers and get_freelancer for profiles and recent reviews, search_offers and get_offer for fixed-price Offers, list_categories for what buyers usually pay. Posting the project, contacting a freelancer and paying stay on PeoplePerHour.
Do I need a paid PeoplePerHour plan or a freelancer account?
No. A free buyer account is enough for all 17 tools.
Does get_project return the project's skills?
No, because PeoplePerHour's project data has no list of skills. The skills are in the brief text, which an agent reads.
Why does it need my Chrome?
To read your PeoplePerHour session without your password. Chrome is used once per sign-in, not for each call.
What happens when PeoplePerHour signs me out?
Calls fail with auth_expired. With Chrome remote debugging on, the server reads the new cookies on the next call (click Allow when Chrome asks); otherwise run peopleperhour-mcp connect again.
Can it run on a VPS or in Docker?
Technically yes, with PEOPLEPERHOUR_AUTH_TOKEN. PeoplePerHour then sees your session from a datacenter IP, which looks less like you. For an always-on setup the hosted version keeps your session in your own Cloud Browser on a fixed IP.
Will my PeoplePerHour account get banned?
Requests carry Chrome's fingerprint and go out one at a time, and the tools read only what you could open yourself. Nobody can promise a platform never acts. Keep the polling to what a person would do.
Can I use it at work or for my clients?
At work and in your own business, yes, free. You may not offer it to others as a hosted or managed service. For client work, use Cotlet or write to contact@cotlet.dev.
Is it open source?
The source is public under the Elastic License 2.0: free to use and change, also in your own business, but not to resell as a hosted service.
A tool broke or I need another one.Open an issue with the tool name and the error message.
Allowed: using it for yourself and in your own business, free. Changing the code and sharing it under the same license.
Not allowed: offering it to others as a hosted or managed service, removing the license notices, getting around its limits.
Maintained by Cotlet (@cotletdev). PeoplePerHour is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by PeoplePerHour.