io.github.Octen-Team/octen-mcp

Official

by Octen-Team · TypeScript

URL to LLM-ready markdown — plus per-page category, page_structure, and query-driven highlights.

Converts web pages to LLM-ready markdown with structure analysis and query highlights.

Topics

anthropicclaudeextractllmmcpmodel-context-protocolscrapingtypescriptocten

README.md6 KBView on GitHub

octen-mcp

MCP server for Octen. Plug it into Claude, Cursor, VS Code, Windsurf, or any MCP client to give your agent live web search and URL extraction.

Core capabilities:

search / news_search: search the live web with domain, text, and time filters.
extract: turn one or more URLs into clean, LLM-ready content.

What makes Octen useful for agents is that extract returns more than page text. Each successful result also includes:

category: what the page is about
page_structure: what kind of page it is
highlights: ranked snippets when you pass a query

That lets an agent skip login walls, nav pages, and off-topic URLs before spending tokens on the full body.

Why Octen MCP

Fast

Web search averages 62ms. Fast enough for multi-step MCP workflows.

Accurate

Fresh

Live web data with minute-level updates. Useful for news, prices, and fast-moving pages.

Efficient

Clean highlights, optional full_content, and page labels keep model context relevant.

Quick start

You need an OCTEN_API_KEY from octen.ai.

For most MCP clients, the config is:

json

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": {
        "OCTEN_API_KEY": "your-key-here"
      }
    }
  }
}

Install command by client

Agent	One-line install
Claude Code	`claude mcp add --scope user octen -e OCTEN_API_KEY=your-key-here -- npx -y octen-mcp`
Codex	`codex mcp add octen --env OCTEN_API_KEY=your-key-here -- npx -y octen-mcp`
Gemini CLI	`gemini mcp add octen -e OCTEN_API_KEY=your-key-here -- npx -y octen-mcp`
VS Code	`code --add-mcp '{"name":"octen","command":"npx","args":["-y","octen-mcp"],"env":{"OCTEN_API_KEY":"your-key-here"}}'` (or click a badge above)
Cursor	Add to Cursor (then edit the key), or use the JSON above in `~/.cursor/mcp.json`
Claude Desktop	No CLI — add the JSON above to the config file (see below)

Config file locations

For clients without a CLI installer, drop the JSON config above into:

Claude Desktop: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Cursor: ~/.cursor/mcp.json
VS Code workspace: .vscode/mcp.json (use servers instead of mcpServers)
Windsurf / Cline / other clients: paste it into that client's MCP settings

Tools

Tool	What it does	Best for
`search`	Search the live web with domain, text, time, and content controls	broad web search
`news_search`	Same engine as `search`, fixed to news	current events and timely reporting
`extract`	Fetch 1-20 URLs and return clean content, labels, and optional highlights	summarization, RAG, fact lookup

Reference docs:

Search: docs.octen.ai/api-reference/search
Extract: docs.octen.ai/api-reference/extract

Why agents like this

Most extract tools stop at "here is the page body." Octen helps one step earlier:

Skip bad pages early: page_structure.primary == "No Main Content" tells the agent it hit a login wall, empty shell, or similar non-content page.
Filter by topic early: category helps a pipeline ignore pages outside the target vertical before embedding or summarizing.
Use less context: query returns highlights when the user wants a specific fact instead of the full page.

For the full decision tree and integration patterns, see docs/best-practices.md.

Example prompts

Fetch octen.ai and summarize the main product features.
Search for recent MCP news from the last week.
Fetch these URLs and only summarize the ones whose category is Finance.
Search site:docs.anthropic.com prompt caching and return only the relevant highlights.

Environment variables

Variable	Required	Default
`OCTEN_API_KEY`	yes	—
`OCTEN_API_URL`	no	`https://api.octen.ai`

Local development

bash

git clone https://github.com/Octen-Team/octen-mcp.git
cd octen-mcp
npm install
npm run build
OCTEN_API_KEY=<key> npm run inspect

More docs

Best practices for agent integration: docs/best-practices.md
Search API reference: docs.octen.ai/api-reference/search
Extract API reference: docs.octen.ai/api-reference/extract

License

MIT © Octen

Install

Configuration

Environment variables

OCTEN_API_KEYrequiredsecret

Octen API key. Get one at https://octen.ai (self-serve).

OCTEN_API_URLdefault https://api.octen.ai

Override the Octen API base URL. Default: https://api.octen.ai.

claude_desktop_config.json

{
  "mcpServers": {
    "octen-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "octen-mcp@0.1.5"
      ],
      "env": {
        "OCTEN_API_KEY": "<YOUR_OCTEN_API_KEY>",
        "OCTEN_API_URL": "https://api.octen.ai"
      }
    }
  }
}