Scrape, crawl, map, and search the web through the hosted pline.ai API using structured JSON results.
Also known as grepsr/pline-api, pline-api
- Stars
- 19
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.3.12
- Last commit
- Nov 12, 2026
- License
- MIT
What is pline.ai MCP?
pline.ai is an MCP server. Scrape, crawl, map, and search the web through the hosted pline.ai API using structured JSON results. It exposes 10 tools, such as batch_scrape_cancel, batch_scrape_start, batch_scrape_status.
Summary generated from the project's README
About pline.ai MCP server
Extracting structured data from websites and performing web searches is what pline.ai enables for developers using AI clients. This MCP server acts as a bridge to a hosted API, allowing you to scrape specific pages, crawl entire sites, map website structures, and execute web searches. Because the heavy lifting like browser fetching and orchestration happens on the pline.ai infrastructure, you do not need to run complex local services like Redis or Temporal.
Users can set up the server locally using npx, a prebuilt binary for various operating systems, or a Docker image. To use it, you must provide your own PLINE_API_KEY and optionally a PLINE_BASE_URL. The server provides tools such as scrape, crawl_start, map_site, and search, all of which return results in structured JSON format. For local stdio connections, you can even specify a save_dir to write scrape outputs directly to your filesystem.
What you can do with it
- 1Scrape web pagesRequest the content of a specific URL to receive structured JSON data.
- 2Crawl entire websitesInitiate a crawling process to discover and collect data across multiple site pages.
- 3Map site structuresUse the mapping tool to understand the URL architecture of a domain.
- 4Perform web searchesExecute search queries through the API to find relevant online information.
Written from the project's README. Every use case is checked against a quote from it.
How to install pline.ai MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall pline.ai MCP in Claude Code
$ claude mcp add --env 'PLINE_API_KEY=<YOUR_PLINE_API_KEY>' pline-api -- npx -y pline-apiInstall pline.ai MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pline-api": {
"command": "npx",
"args": [
"-y",
"pline-api"
],
"env": {
"PLINE_API_KEY": "<YOUR_PLINE_API_KEY>"
}
}
}
}Install pline.ai MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pline-api": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pline-api"
],
"env": {
"PLINE_API_KEY": "<YOUR_PLINE_API_KEY>"
}
}
}
}Install pline.ai MCP in VS Code CLI
$ code --add-mcp '{"name":"pline-api","type":"stdio","command":"npx","args":["-y","pline-api"],"env":{"PLINE_API_KEY":"<YOUR_PLINE_API_KEY>"}}'Install pline.ai MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pline-api": {
"command": "npx",
"args": [
"-y",
"pline-api"
],
"env": {
"PLINE_API_KEY": "<YOUR_PLINE_API_KEY>"
}
}
}
}Install pline.ai MCP in Codex
$ codex mcp add pline-api --env 'PLINE_API_KEY=<YOUR_PLINE_API_KEY>' --env 'PLINE_API_KEY=<YOUR_PLINE_API_KEY>' -- npx -y pline-apiInstall pline.ai MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pline-api] command = "npx" args = ["-y", "pline-api"] [mcp_servers.pline-api.env] PLINE_API_KEY = "<YOUR_PLINE_API_KEY>"
Install pline.ai MCP in Gemini CLI
$ gemini mcp add -s user -e 'PLINE_API_KEY=<YOUR_PLINE_API_KEY>' -e 'PLINE_API_KEY=<YOUR_PLINE_API_KEY>' pline-api npx -- -y pline-apiInstall pline.ai MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pline-api": {
"command": "npx",
"args": [
"-y",
"pline-api"
],
"env": {
"PLINE_API_KEY": "<YOUR_PLINE_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pline-api 0.3.12 in an isolated container with no network and no keys. It answered and listed 10 tools.
pline.ai MCP tools 10
Read from the server with tools/listbatch_scrape_cancelActionRequest cancellation of a batch scrape job (DELETE /batch/scrape/{id}). 409 if already finished.
batch_scrape_startActionScrape a known list of URLs as one durable background job (POST /batch/scrape). Returns 202 metadata with the job id. Poll with batch_scrape_status. Completed jobs expose one JSONL artifact per output format, one line per URL: index, url, success, status, finalUrl, output, error. Cheaper and more predictable than a crawl when the URLs are already known. API docs: https://apidocs.pline.ai/guides/endpoints/batch-scrape
batch_scrape_statusActionRead a batch scrape job's progress (GET /batch/scrape/{id}). status is scraping | completed | failed | cancelled with completed/failed/pending/inFlight counts. On completion s3PresignedUrls maps each format to an expiring JSONL download. Long jobs are fine to leave running: report the id instead of blocking.
crawl_cancelActionRequest cancellation of a crawl job (DELETE /crawl/{id}). 409 if already finished.
crawl_startActionDiscover and scrape a whole site by following links, as a durable background job (POST /crawl). Returns 202 metadata with the job id. Poll with crawl_status. Completed jobs expose one ZIP per format with a manifest.json mapping files to source URLs. Scope it first: an unscoped crawl of a large site burns credits fast, and map_site shows what a crawl would hit for one cheap call. API docs: https://apidocs.pline.ai/guides/endpoints/crawl
crawl_statusActionRead a crawl job's progress (GET /crawl/{id}). status is scraping | completed | failed | cancelled with completed/failed/pending/inFlight counts. On completion s3PresignedUrls maps each format to an expiring ZIP download. Long jobs are fine to leave running: report the id instead of blocking.
map_siteRead-onlyList a site's URLs synchronously (POST /map), each with a type classification plus title and description when known. Cheap. Use it to size up a site before crawl_start, or when only the URL list is needed. API docs: https://apidocs.pline.ai/guides/endpoints/map
scrapeActionFetch one page synchronously and return its content in the requested formats (POST /scrape). Returns the flat pline.ai response: data (keyed by output), status (the page's HTTP status), final_url, session_id, request_id, effective_geolocation, site_tier. A 200 with empty data is a soft failure: retry with js_render=true if it was unset, or drop a proxy_strategy pin. The session returned is remembered per host and reused on the next scrape of that host. API docs: https://apidocs.pline.ai/guides/endpoints/scrape
searchRead-onlySearch the web (GET /serp) and return organic results, plus search features in full mode. Organic results carry position, title, link, snippet, domain, page, and html_body/clean_html/links when output was requested. API docs: https://apidocs.pline.ai/guides/endpoints/serp
sessions_listRead-onlyReturn the host -> session_id map this server is reusing for you. Empty until the first scrape.
| batch_scrape_cancel | Request cancellation of a batch scrape job (DELETE /batch/scrape/{id}). 409 if already finished. | Action |
| batch_scrape_start | Scrape a known list of URLs as one durable background job (POST /batch/scrape). Returns 202 metadata with the job id. Poll with batch_scrape_status. Completed jobs expose one JSONL artifact per output format, one line per URL: index, url, success, status, finalUrl, output, error. Cheaper and more predictable than a crawl when the URLs are already known. API docs: https://apidocs.pline.ai/guides/endpoints/batch-scrape | Action |
| batch_scrape_status | Read a batch scrape job's progress (GET /batch/scrape/{id}). status is scraping | completed | failed | cancelled with completed/failed/pending/inFlight counts. On completion s3PresignedUrls maps each format to an expiring JSONL download. Long jobs are fine to leave running: report the id instead of blocking. | Action |
| crawl_cancel | Request cancellation of a crawl job (DELETE /crawl/{id}). 409 if already finished. | Action |
| crawl_start | Discover and scrape a whole site by following links, as a durable background job (POST /crawl). Returns 202 metadata with the job id. Poll with crawl_status. Completed jobs expose one ZIP per format with a manifest.json mapping files to source URLs. Scope it first: an unscoped crawl of a large site burns credits fast, and map_site shows what a crawl would hit for one cheap call. API docs: https://apidocs.pline.ai/guides/endpoints/crawl | Action |
| crawl_status | Read a crawl job's progress (GET /crawl/{id}). status is scraping | completed | failed | cancelled with completed/failed/pending/inFlight counts. On completion s3PresignedUrls maps each format to an expiring ZIP download. Long jobs are fine to leave running: report the id instead of blocking. | Action |
| map_site | List a site's URLs synchronously (POST /map), each with a type classification plus title and description when known. Cheap. Use it to size up a site before crawl_start, or when only the URL list is needed. API docs: https://apidocs.pline.ai/guides/endpoints/map | Read-only |
| scrape | Fetch one page synchronously and return its content in the requested formats (POST /scrape). Returns the flat pline.ai response: data (keyed by output), status (the page's HTTP status), final_url, session_id, request_id, effective_geolocation, site_tier. A 200 with empty data is a soft failure: retry with js_render=true if it was unset, or drop a proxy_strategy pin. The session returned is remembered per host and reused on the next scrape of that host. API docs: https://apidocs.pline.ai/guides/endpoints/scrape | Action |
| search | Search the web (GET /serp) and return organic results, plus search features in full mode. Organic results carry position, title, link, snippet, domain, page, and html_body/clean_html/links when output was requested. API docs: https://apidocs.pline.ai/guides/endpoints/serp | Read-only |
| sessions_list | Return the host -> session_id map this server is reusing for you. Empty until the first scrape. | Read-only |
Configuration
PLINE_API_KEYRequiredSecretYour own pline.ai API key. Sent to the API as the x-api-key header.
PLINE_API_KEYRequiredSecretYour own pline.ai API key. Sent to the API as the x-api-key header.
PLINE_BASE_URLpline.ai API base URL. Optional; defaults to https://apix.pline.ai/v1.
PLINE_BASE_URLpline.ai API base URL. Optional; defaults to https://apix.pline.ai/v1.
| Name | Description | |
|---|---|---|
| PLINE_API_KEY | Your own pline.ai API key. Sent to the API as the x-api-key header. | RequiredSecret |
| PLINE_API_KEY | Your own pline.ai API key. Sent to the API as the x-api-key header. | RequiredSecret |
| PLINE_BASE_URL | pline.ai API base URL. Optional; defaults to https://apix.pline.ai/v1. | |
| PLINE_BASE_URL | pline.ai API base URL. Optional; defaults to https://apix.pline.ai/v1. |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablegrepsr/pline-api is public and reachablegithub.com/grepsr/pline-api ↗Pass
- Package names this repository as its sourcepline-api names grepsr/pline-api as sourcenpmjs.com/package/pline-api ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for pline-apinpmjs.com/package/pline-api/v/0.3.12#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/grepsr/pline-api ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from pline-apiPass
- No critical advisory in the package or its dependencies6 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpline.ai MCP server
Run this MCP server on your own machine to scrape pages, crawl sites, discover URLs, and search through the hosted pline.ai API. Each user supplies their own API key.
Your MCP client → local MCP process (stdio) → hosted pline.ai API (HTTPS)
The scraping backend stays on pline.ai's infrastructure. You do not need to run the orchestrator, browser fetcher, Redis, or Temporal locally.
Run with npx
The server is published to npm as pline-api: a small
launcher that selects the prebuilt binary for your platform (macOS arm64/x64, Linux x64/arm64,
Windows x64) from an optional dependency, falling back to a checksum-verified download from the
GitHub Release. Node.js 18+ is the only requirement:
{
"mcpServers": {
"pline.ai": {
"command": "npx",
"args": ["-y", "pline-api"],
"env": {
"PLINE_BASE_URL": "https://apix.pline.ai/v1",
"PLINE_API_KEY": "your-own-api-key"
}
}
}
}
Arguments pass straight through to the binary (npx -y pline-api --http 127.0.0.1:8080), and
PLINE_MCP_BINARY=/path/to/pline-mcp makes the launcher run a build of your own. The launcher
source is in ../npm; per-platform packages are named pline-api-<os>-<cpu>.
Install a prebuilt binary
Use the platform downloads and checksum instructions in the
repository setup guide. Extract pline-mcp (or
pline-mcp.exe on Windows) and configure your MCP client with its absolute path below.
You do not need Rust, Cargo, or a repository checkout for a prebuilt installation.
Run the Docker image
Each release is also published as a multi-platform image at
ghcr.io/grepsr/pline-mcp (linux/amd64 and linux/arm64), which is the package the
MCP Registry entry io.github.grepsr/pline-api points at.
With Docker installed, an MCP client can run the server over stdio without downloading a binary:
{
"mcpServers": {
"pline.ai": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "PLINE_BASE_URL", "-e", "PLINE_API_KEY",
"ghcr.io/grepsr/pline-mcp:0.3.12", "--stdio"],
"env": {
"PLINE_BASE_URL": "https://apix.pline.ai/v1",
"PLINE_API_KEY": "your-own-api-key"
}
}
}
}
-e NAME without a value forwards the variable from the client-provided environment into the
container, so the key never appears on the command line. The image runs as an unprivileged user and
has no access to your filesystem, so save_dir and download_dir are unavailable unless you mount a
volume. Pin the tag to a release version; latest moves. The same image serves Streamable HTTP when
started without --stdio:
docker run --rm -p 8080:8080 -e PLINE_BASE_URL=https://apix.pline.ai/v1 ghcr.io/grepsr/pline-mcp:0.3.12
Build from Git
You need Git, a current stable Rust toolchain with Cargo, and an API key. The server calls the public
API at https://apix.pline.ai/v1 unless PLINE_BASE_URL overrides it.
From the repository root:
git clone https://github.com/grepsr/pline-api.git
cd pline-api
cargo build --manifest-path mcp-server/Cargo.toml --release --locked
cp .env.example .env
Edit .env with your API URL and your own key, then load it before starting your MCP client:
set -a
. ./.env
set +a
These environment-loading commands are for POSIX shells. On other platforms, set the same two
environment variables in your shell or MCP client configuration. The server does not load .env
automatically; the file is ignored by Git.
PLINE_BASE_URL is optional and defaults to the public API, https://apix.pline.ai/v1. Internal
deployment addresses are not reachable from a user's machine.
Connect an MCP client
For a client with a mcpServers JSON configuration, add this entry. Replace the binary path, API
URL, and key with your own values. On Windows the binary has an .exe suffix.
{
"mcpServers": {
"pline.ai": {
"command": "/absolute/path/to/pline-mcp",
"args": ["--stdio"],
"env": {
"PLINE_BASE_URL": "https://apix.pline.ai/v1",
"PLINE_API_KEY": "your-own-api-key"
}
}
}
}
Use an absolute binary path so the client can launch it from any working directory.
For source builds, the executable is mcp-server/target/release/pline-mcp inside the checkout. Store real
credentials in your local client settings, not in a committed configuration file.
For Claude Code launched from the repository root, the root .mcp.json runs the server through
Cargo and expands the two environment variables from your shell. The first release build can
take a while; building it first avoids waiting during the client's connection attempt.
The MCP client launches and manages the stdio process. You do not need to start an HTTP listener
or expose a port. Logs go to stderr (RUST_LOG=debug for more detail).
Update
For prebuilt installs, download the new archive, verify its checksum, and replace the executable. For source builds:
git pull --ff-only
cargo build --manifest-path mcp-server/Cargo.toml --release --locked
Restart or reconnect the MCP client to load the rebuilt binary.
Tools
| Tool | Endpoint |
|---|---|
scrape |
POST /scrape |
batch_scrape_start / batch_scrape_status / batch_scrape_cancel |
/batch/scrape |
crawl_start / crawl_status / crawl_cancel |
/crawl |
map_site |
POST /map |
search |
GET /serp |
sessions_list |
local: remembered host-to-session map for this caller |
Tool results contain structured JSON. API errors return the HTTP status and the service's
detail message. The client sends your key to the configured API as x-api-key.
scrape remembers sessions per caller and host for the process lifetime. A second scrape of the
same host reuses the session unless you pass session_id or set new_session=true. Same-host
scrapes are serialized locally. A 4xx response on a remembered session drops it for the next call.
Over stdio, save_dir writes scrape outputs to your local filesystem and returns their paths. Without it,
outputs are clipped at max_chars (default 60000); truncated_outputs lists clipped fields.
Over stdio, the status tools can download finished job artifacts to a local download_dir.
HTTP requests with save_dir or download_dir are rejected before contacting the API.
Read pline://guide for usage guidance and pline://reference for the API fields and constraints.
The documents are also available in docs/guide.md and
docs/reference.md.
Hosted OAuth connection
The remote MCP endpoint can use Pline sign-in instead of asking every agent user to paste an API
key. After sign-in, each user selects a workspace and an active API key. Follow
docs/oauth-hosting.md to configure the Pline web app and host.
Configuration
The executable is pline-mcp; its public MCP identity is pline.ai.
Set PLINE_BASE_URL and PLINE_API_KEY for local stdio use.
For HTTP mode, PLINE_MCP_HTTP_ADDR sets the listener address and
PLINE_MCP_ALLOWED_HOSTS accepts a comma-separated list of allowed hosts. OAuth mode also uses
PLINE_PLATFORM_BASE_URL (Pline web app origin), PLINE_SUPABASE_URL (Supabase project origin),
and PLINE_MCP_PUBLIC_URL (public MCP origin).
Where this server is listed
The server is published to the official MCP Registry as io.github.grepsr/pline-api with the npm
package and the GHCR image above as its packages, and the repository root is installable as a Claude
Code plugin (pline-ai) that runs the npm package. The root .cursor/mcp.json
and .vscode/mcp.json configure npx -y pline-api for Cursor and VS Code
workspaces. PUBLISHING.md describes how each listing is produced and kept current.
HTTP mode
The binary also supports Streamable HTTP, for example for local transport development:
PLINE_BASE_URL=https://apix.pline.ai/v1 \
./mcp-server/target/release/pline-mcp --http 127.0.0.1:8080
/health reports liveness. /openapi.json serves a public OpenAPI 3.1 description of the server,
generated from the live tool list. /mcp accepts the caller's API key through Authorization: Bearer or
x-api-key; the legacy /<key>/mcp route also exists, but puts credentials in URLs and access logs.
The server forwards each caller's key rather than using the stdio environment key. A Supabase OAuth
access token is also accepted when the platform and OAuth environment variables are configured. The
user selects an active workspace API key in Pline's OAuth consent screen, and the server resolves it
for each request through the authenticated Pline platform. The MCP process does not keep a shared API
key.
Configure Supabase OAuth 2.1 with dynamic client registration enabled and /oauth/consent as its
authorization UI path. Apply API service migrations with uv run alembic upgrade head from the
pline-hades-api-service repository before enabling the hosted endpoint.
HTTP transport is stateless: no Mcp-Session-Id is issued, and standalone GET streams and DELETE
session requests return 405. Each POST uses its own API key; remembered scrape sessions remain
scoped to that key. Session replay and MCP cancellation notifications are not supported in HTTP
mode. The Git installation above uses stdio.
Develop
Run from mcp-server/:
cargo test --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo fmt --check
The guide and reference are embedded with include_str!; rebuild after editing them.
pline.ai MCP questions
How do I add pline.ai MCP to Claude Code?
Run claude mcp add --env 'PLINE_API_KEY=<YOUR_PLINE_API_KEY>' pline-api -- npx -y pline-api in your terminal. Add --scope user to make it available in every project.
How do I add pline.ai MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does pline.ai MCP provide?
It exposes 10 tools, including batch_scrape_cancel, batch_scrape_start, batch_scrape_status, crawl_cancel, crawl_start.
What do I need to run this server?
You only need Node.js 18+ to run the server via npx, or you can use a prebuilt binary or a Docker image.
Do I need to run the scraping infrastructure locally?
No, the scraping backend remains on pline.ai's infrastructure, so you don't need to run the orchestrator, browser fetcher, Redis, or Temporal locally.
How are the results returned?
The tools provide results in structured JSON format.
Can I save scraped data to my local machine?
Yes, when running over stdio, you can use the save_dir argument to write outputs to your local filesystem.