# Octoparse Mcp

> Official Octoparse MCP server for AI-powered web scraping workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-octoparse-octoparse-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [octoparse](https://agentstack.voostack.com/s/octoparse)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [octoparse](https://github.com/octoparse)
- **Source:** https://github.com/octoparse/octoparse-mcp

## Install

```sh
agentstack add mcp-octoparse-octoparse-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Octoparse MCP Server

[](https://www.octoparse.com/)
[](https://openapi.octoparse.com/octoparse-mcp-guide.html)

[English](README.md) | [日本語](README-ja.md)

Octoparse MCP Server connects MCP-compatible AI clients to Octoparse so users can discover scraping templates, run cloud extraction tasks, manage existing tasks, and export structured data.

## Hosted Server

Use the hosted Streamable HTTP endpoint:

```text
https://mcp.octoparse.com
```

Configure this as an MCP server endpoint, not as a REST API tool.

## Authentication

The hosted server officially supports both OAuth and API key authentication:

- OAuth: the default option when the MCP client can open a browser authorization flow.
- API key: an optional authentication method for clients that can send custom HTTP headers.

For API key mode, send the key in the `x-api-key` header. Do not place real keys in source control, issue reports, screenshots, or shared logs.

## Quick Start

Generic HTTP MCP configuration:

```json
{
  "mcpServers": {
    "octoparse": {
      "type": "http",
      "url": "https://mcp.octoparse.com"
    }
  }
}
```

Claude OAuth / default authentication:

```bash
claude mcp add --transport http octoparse https://mcp.octoparse.com
```

Claude with API key:

```bash
claude mcp add --transport http octoparse https://mcp.octoparse.com --header "x-api-key: YOUR_API_KEY"
```

Codex CLI:

```bash
codex mcp add octoparse --url https://mcp.octoparse.com
```

Gemini CLI example configuration:

```json
{
  "mcpServers": {
    "octoparse": {
      "httpUrl": "https://mcp.octoparse.com",
      "oauth": {
        "clientId": "Octoparse",
        "enabled": true
      }
    }
  }
}
```

After adding the server, complete authorization in the browser if your client prompts for OAuth.

More client examples are in [Configuration](docs/Configuration.md).

## Tools

| Tool | Purpose |
| --- | --- |
| `search_templates` | Find Octoparse templates by keyword, template ID, or slug. |
| `execute_task` | Validate parameters, create a cloud task, and start extraction. |
| `export_data` | Export task results as JSON, CSV, Excel, HTML, or XML when data is ready. |
| `search_tasks` | Search existing tasks in the authenticated account. |
| `start_or_stop_task` | Start or stop an existing cloud task by task ID. |
| `redeem_coupon_code` | Redeem a promotion, coupon, or resource code supplied by the user. |

See [Tools](docs/Tools.md) for inputs, examples, and common failure cases.

## Typical Workflow

```text
search_templates -> execute_task -> export_data
```

Example user prompt:

```text
Find a cloud-capable Octoparse template for Amazon product listings, run it for wireless earbuds, and export the result as CSV.
```

For an existing task, use:

```text
search_tasks -> export_data
```

Scheduling, notifications, recurring jobs, and external automations are handled by the MCP client or another automation system. The MCP server exposes task and export tools; it does not provide a standalone scheduler.

## Scope

Octoparse MCP Server can:

- Search the Octoparse template library.
- Run cloud-capable template tasks.
- Validate template parameters before execution.
- Export collected data when a task has data available.
- Search, start, and stop existing cloud tasks.

It does not:

- Run local-only desktop tasks through the hosted server.
- Create or edit arbitrary custom scraping workflows.
- Upload private templates.
- Provide billing or account administration tools.
- Schedule recurring runs by itself.

## Common Limits

- Some templates are local-only and must be run in the Octoparse desktop app.
- Cloud execution depends on account permissions, available credits or quota, target-site availability, and template support.
- Long-running tasks may need follow-up calls. If data is still collecting or exporting, wait and call `export_data` again.
- Tool availability can be narrowed with `includeTools` or `excludeTools` URL parameters. See [Overview](docs/Overview.md).

## Security

- Keep API keys and OAuth tokens out of Git, logs, screenshots, and public issues.
- Use OAuth when possible for interactive clients.
- Use `x-api-key` only with clients that store headers securely.
- Report vulnerabilities privately. See [Security](SECURITY.md).

## Documentation

- [Overview](docs/Overview.md)
- [Configuration](docs/Configuration.md)
- [Tools](docs/Tools.md)
- [Troubleshooting](docs/Troubleshooting.md)
- [Octoparse API Docs](https://openapi.octoparse.com/en-US)
- [Help Center](https://helpcenter.octoparse.com)
- [Available on Smithery](https://smithery.ai/servers/octoparse/octoparse-mcp-server)

## Development

```bash
npm install
npm run build
npm test
```

For local environment variables, copy `.env.example` to `.env` and fill only values needed for your environment. Never commit `.env`.

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening issues or pull requests.

## License

MIT. See [LICENSE.md](LICENSE.md).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [octoparse](https://github.com/octoparse)
- **Source:** [octoparse/octoparse-mcp](https://github.com/octoparse/octoparse-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-octoparse-octoparse-mcp
- Seller: https://agentstack.voostack.com/s/octoparse
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.