PeoplePerHour API and MCP server, self-hosted

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.

It is for technical people who want to run it themselves, for personal use only (license). If you want it running 24/7 on a server, kept working when PeoplePerHour changes its site, for a team or a business, use the hosted version at cotlet.dev.

git clone https://github.com/cotletdev/peopleperhour-api-mcp-server.git && cd peopleperhour-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
peopleperhour-mcp connect                          # reads your PeoplePerHour session from Chrome
peopleperhour-mcp call search_projects query="web design" limit=5
claude mcp add peopleperhour -- "$PWD/.venv/bin/peopleperhour-mcp" mcp

Contents

• How it works

• Requirements

• Install

• Connect your Chrome

• MCP server

• REST API

• Python and the example scripts

• All 17 tools

• Configuration

• Security and your PeoplePerHour account

• Errors

• Self-hosted or hosted

• FAQ

• License

Related MCP server: Upwork MCP Server

How it works

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)

1. You sign in to PeoplePerHour in your own Chrome, the way you always do. Tick Remember me.

2. 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.

3. 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.

Install

git clone https://github.com/cotletdev/peopleperhour-api-mcp-server.git
cd peopleperhour-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
peopleperhour-mcp --version

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: 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)

1. 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.

2. Make sure you are signed in at peopleperhour.com.

3. Run:

   peopleperhour-mcp connect

4. Chrome asks whether to allow the connection. Click Allow.

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:

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-pph"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-pph"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-pph"

peopleperhour-mcp connect --cdp http://127.0.0.1:9222

--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:

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:

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

claude mcp add peopleperhour -- /path/to/peopleperhour-api-mcp-server/.venv/bin/peopleperhour-mcp mcp

Claude Desktop

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

{
  "mcpServers": {
    "peopleperhour": {
      "command": "/path/to/peopleperhour-api-mcp-server/.venv/bin/peopleperhour-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json, the same block as Claude Desktop. A ready copy is in mcp.json.

Codex

~/.codex/config.toml:

[mcp_servers.peopleperhour]
command = "/path/to/peopleperhour-api-mcp-server/.venv/bin/peopleperhour-mcp"
args = ["mcp"]

Over HTTP

peopleperhour-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:

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

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.

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:

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>:

PEOPLEPERHOUR_MCP_TOKEN=$(openssl rand -hex 24) peopleperhour-mcp serve --host 0.0.0.0

Python and the example scripts

Straight from Python, no server needed:

from peopleperhour_api_mcp import call
from peopleperhour_api_mcp.scripting import paginate, write_rows

new = list(paginate("search_projects", {"query": "logo", "since": "2026-10-21T00:00:00Z"}, "projects"))
write_rows(new, "projects.csv")
brief = call("get_project", project_id=new[0]["project_id"])["brief"]

Or one tool from the shell: peopleperhour-mcp call get_project project_id=4527712, or with a JSON object.

Ready scripts in examples/, one per job on the integration page. Each takes --help, and the list scripts take --out file.csv or --out file.json:

python examples/find_new_projects.py --query "web design" --query webflow --hours 24 --min-budget 200 --max-proposals 15
python examples/read_project_brief.py 4527712
python examples/shortlist_freelancers.py "logo design" --hourly-rate 10-30 --min-rating 80
python examples/median_budgets.py translation --currency USD

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

Watchlist

Saved searches

Freelancers

Offers

Account, notifications and WorkStreams

Categories

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

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.

Self-hosted or hosted

On the hosted version a successful call uses 20 to 30 credits (25 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

Does PeoplePerHour have an official 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. Details: cotlet.dev/integrations/peopleperhour-api-mcp-server.

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, and the license allows it only on a server you alone use. 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? No, the license is for personal use by one person. For a team, a company or client work, use Cotlet or write to contact@cotlet.dev.

Is it open source? The source is public, the license is not an open source license: personal use only, no business use, no hosting for others.

A tool broke or I need another one. Open an issue with the tool name and the error message.

License

Cotlet Personal Use License 1.0. In short:

• Allowed: one person, on their own computers, with their own PeoplePerHour accounts, for their own purposes. Changing the code for yourself, and a GitHub fork under the same license.

• Not allowed: any use in or for a company or organization, your own business included; letting other people use your instance (shared server, team machine, cloud service); selling or offering it or a service built on it.

Maintained by Cotlet (@cotletdev). PeoplePerHour is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by PeoplePerHour.