Skip to main content
Glama
openserpapi

OpenSERP Cloud

Official
by openserpapi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

@openserp/mcp

npm version license

Model Context Protocol server for OpenSERP OSS and OpenSERP Cloud. It gives MCP clients search, image search, single and batch URL extraction, usage, and engine metadata tools.

When OPENSERP_API_KEY is not set, the server uses OSS mode at http://localhost:7000 and writes:

[openserp-mcp] No OPENSERP_API_KEY set - using OSS mode at http://localhost:7000.
[openserp-mcp] Get an API key: https://openserp.org/dashboard/keys
[openserp-mcp] Docs: https://openserp.org/docs | Issues: https://github.com/openserpapi/mcp/issues

Set OPENSERP_API_KEY to use OpenSERP Cloud. API keys are available at https://openserp.org/dashboard/keys. Set OPENSERP_BASE_URL to target another compatible OpenSERP API base URL.

Install

npm install -g @openserp/mcp

You can also run it without installing:

npx -y @openserp/mcp --stdio

Related MCP server: Google Cheap Search

Tools

  • search

  • mega_search

  • fast_search

  • any_search

  • image_search

  • mega_image

  • get_usage

  • list_engines

  • extract

  • batch_extract

Quick Examples

Ask your MCP client to:

  • Search Google for current docs and return the top 5 URLs.

  • Compare Google and Bing results for an SEO keyword.

  • Extract clean Markdown from a URL before passing it to an LLM.

  • Ground an answer in several sources at once with batch_extract - up to 20 URLs in one round-trip, where a dead link returns an error item instead of failing the batch.

  • Read a geo-fenced page as a local visitor by passing region: "DE".

  • Check remaining Cloud credits with get_usage.

Claude Desktop

Local OSS mode:

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"]
    }
  }
}

Cloud mode:

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"],
      "env": {
        "OPENSERP_API_KEY": "osk_live_..."
      }
    }
  }
}

Cursor

For stdio use, add an MCP server entry:

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"],
      "env": {
        "OPENSERP_API_KEY": "osk_live_..."
      }
    }
  }
}

For remote-style HTTP use, run:

npx -y @openserp/mcp --http --host 127.0.0.1 --port 3333

Then point a streamable HTTP MCP client to:

http://127.0.0.1:3333/mcp

Clients that still use the older SSE transport can connect to:

http://127.0.0.1:3333/sse

Environment

  • OPENSERP_API_KEY: Cloud API key from https://openserp.org/dashboard/keys.

  • OPENSERP_BASE_URL: API base URL override.

  • OPENSERP_BACKEND: Optional backend hint, oss or cloud.

  • OPENSERP_TIMEOUT_MS: SDK request timeout in milliseconds.

  • HOST: HTTP host, default 127.0.0.1.

  • PORT: HTTP port, default 3333.

Resources

Available Tools

9 tools
extractExtract URLB

Extract LLM-ready content from a URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesAbsolute URL to fetch and extract.
langNoLanguage hint.
modeNoExtraction strategy.auto
cleanNoUse article-only extraction when true.
formatNoResponse format.json
minRunesNoMinimum content length (in runes) before auto mode escalates to rendered extraction.
useLlmsTxtNoPrefer /llms-full.txt or /llms.txt for site roots.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits. It only says 'LLM-ready content' without explaining extraction behavior, failure handling, or output characteristics. This is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no filler. However, it may be too concise given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 7 parameters and no output schema or annotations, the description adds minimal context. Agents need more detail on extraction strategies, output format effects, and edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all 7 parameters with descriptions, so the baseline is 3. The tool description adds no extra parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Extract') and a clear resource ('LLM-ready content from a URL'). It distinguishes this tool from sibling search tools by emphasizing LLM-readiness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lacks any guidance on when to use this tool versus alternatives or when not to use it. No context about prerequisites or limitations is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_usageGet UsageA

Return OpenSERP Cloud account and credit information.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; the description states it returns account and credit info but discloses no side effects, permissions required, or reliability guarantees. Minimal behavioral insight beyond the stated purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Front-loaded with the key action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description is minimally sufficient but could be more specific (e.g., 'credit balance' or 'usage limits'). Lacks detail on return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; schema coverage is 100% by default. The description adds no param info, but none is needed. Baseline for 0 params is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and resource ('OpenSERP Cloud account and credit information'), clearly distinguishing this tool from sibling search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or not use this tool versus alternatives. The context of being a zero-parameter info tool implies distinct usage, but the description lacks explicit context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_enginesList EnginesB

List available engines on OSS or Cloud engine capabilities on Cloud.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It does not disclose whether the operation is read-only, requires authentication, or returns any specific data format. The description is insufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with one sentence. It is front-loaded but lacks structure. It is appropriate for the simplicity of the tool, though a slightly more detailed description would improve usability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description provides a basic idea but omits details about the format or structure of the list. It is minimally adequate but not rich in context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed. It could benefit from explaining what the output represents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists available engines and distinguishes between OSS and Cloud capabilities. It is specific and distinct from sibling tools, though the phrasing is slightly ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like any_search or get_usage. The context for using list_engines is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mega_imageMega Image SearchC

Search images across multiple engines.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoDate interval in YYYYMMDD..YYYYMMDD format.
fileNoFile extension filter, such as PDF.
langNoLanguage code, such as EN or de.
modeNoMega execution mode.balanced
siteNoDomain filter, such as example.com.
textNoSearch query text. At least one of text, site, or file should be provided.
limitNoMaximum result count.
mergeNoMerge successful engine results.
startNoPagination offset.
dedupeNoDeduplicate by normalized URL.
filterNoEnable duplicate filtering.
formatNoResponse format.json
regionNoMarket or location hint, such as US, DE, en-GB, Berlin, or a Yandex lr id.
enginesNoEngines to query. Omit to use all available engines.
featuresNoInclude supported rich SERP features.

TDQS

C2.4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description fails to mention any behavioral traits such as merging, deduplication, rate limits, or required permissions. The description is silent on side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise but under-specified. It lacks necessary context for an agent to use the tool effectively, making it too terse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 15 parameters and no output schema, the description is woefully incomplete. It does not explain return values, pagination, or how to combine parameters for effective searches.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema definitions; it does not explain how parameters like 'merge', 'dedupe', or 'filter' affect behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches images across multiple engines, which distinguishes it from single-engine image search tools like 'image_search' or general 'mega_search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'image_search' or 'mega_search'. Does not specify prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv0.1.6
    • First observedany_search
    • First observedextract
    • First observedfast_search
    • First observedget_usage
    • First observedimage_search
    • First observedlist_engines
    • First observedmega_image
    • First observedmega_search
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 9 tools

Disambiguation3/5

Several search tools (any_search, fast_search, search, mega_search) have overlapping purposes with subtle differences, which may confuse an agent. Descriptions provide some clarity but boundaries remain fuzzy.

Naming Consistency3/5

Naming mixes verb_noun (get_usage, list_engines) with modifier_noun (any_search, fast_search) and a single verb (extract), lacking a uniform pattern but remains readable.

Tool Count5/5

With 9 tools, the set is well-scoped for a search and extraction API, neither too sparse nor cluttered.

Completeness4/5

Covers core search, image search, extraction, engine listing, and account info. Minor redundancy but no critical gaps for the intended domain.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Serpapi Universal MCP Server

    universal-mcp
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides a standardized interface to interact with Serpapi's search engine results API, enabling users to perform web searches and retrieve structured data.
    1
    MIT

  • Google Cheap Search

    SerpCheap
    A
    license
    A
    quality
    D
    maintenance
    Provides real-time Google search results (organic + knowledge graph) with country targeting, language, time filters, and pagination, at low cost.
    1
    7 npm
    MIT

  • web-search-mcp

    Backerss
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides free web search, content fetching, image search, and deep research via SearXNG, no API keys required.
    -

  • GroundRoute

    PROJECT-B-26
    A
    license
    A
    quality
    D
    maintenance
    Web search for AI agents across 6 engines (Serper, Brave, Exa, Tavily, Firecrawl, Perplexity) through one search tool. Routes each query to the cheapest engine that clears a quality bar and caches repeats. Hosted, streamable-HTTP, BYOK supported.
    1
    1
    MIT

Appeared in Searches