Tinyfish Search Fetch

A lightweight, stdio-based Model Context Protocol (MCP) server designed to provide search and fetch capabilities through the TinyFish ecosystem.

Note: This MCP server provides access exclusively to the TinyFish Free Access API (Search & Fetch).

Overview

TinyFish Search/Fetch MCP Server is a standalone MCP server that offers web search via the TinyFish Search API and content fetching via the TinyFish Fetch API. It uses stdio transport for seamless integration with MCP-compatible clients such as Claude Desktop, Cursor, Windsurf, or any custom client supporting the stdio protocol.

Features

• Search: Quickly find relevant information using TinyFish search capabilities.
• Fetch: Retrieve content from web resources efficiently.
• Burst Fetch: Fetch and extract clean content from up to 10 URLs in a single request.
• Stdio Transport: Designed for seamless integration with MCP clients (e.g. Claude Desktop, Cursor).

Available Tools

search

Search the web using TinyFish Search API.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query. Search operators such as site:example.com may be used.
location	string	No	Country code, e.g. JP, US, GB, FR.
language	string	No	Language code, e.g. ja, en, fr.
max_results	integer	No	Local truncation count for returned results. Must be positive.

Returns: JSON text containing the TinyFish search response.

fetch_content

Fetch and extract clean content from a single URL using TinyFish Fetch API.

Parameters:

Parameter	Type	Required	Description
url	string	Yes	URL to fetch. Must use http or https scheme.
format	string	No	Output format: markdown (default), html, or json.
links	boolean	No	Include extracted page links when supported. Default: false.
image_links	boolean	No	Include extracted image links when supported. Default: false.

Returns: JSON text containing the TinyFish fetch response.

fetch_contents

Fetch and extract clean content from up to 10 URLs using TinyFish Fetch API.

Parameters:

Parameter	Type	Required	Description
urls	string[]	Yes	Non-empty list of URLs to fetch. Maximum 10. Each must use http or https scheme.
format	string	No	Output format: markdown (default), html, or json.
links	boolean	No	Include extracted page links when supported. Default: false.
image_links	boolean	No	Include extracted image links when supported. Default: false.

Returns: JSON text containing the TinyFish fetch response.

Tool Schemas

search

{
  "name": "search",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query. Search operators such as site:example.com may be used."
      },
      "location": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Optional country code, e.g. JP, US, GB, FR."
      },
      "language": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Optional language code, e.g. ja, en, fr."
      },
      "max_results": {
        "anyOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "minimum": 1,
        "description": "Optional local truncation count for returned results."
      }
    },
    "required": ["query"]
  }
}

fetch_content

{
  "name": "fetch_content",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "url": {
        "type": "string",
        "description": "URL to fetch. Must be http or https."
      },
      "format": {
        "type": "string",
        "enum": ["markdown", "html", "json"],
        "default": "markdown",
        "description": "Output format: markdown, html, or json."
      },
      "links": {
        "type": "boolean",
        "default": false,
        "description": "Include extracted page links when supported."
      },
      "image_links": {
        "type": "boolean",
        "default": false,
        "description": "Include extracted image links when supported."
      }
    },
    "required": ["url"]
  }
}

fetch_contents

{
  "name": "fetch_contents",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "urls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1,
        "maxItems": 10,
        "description": "URLs to fetch. Maximum 10. Each must be http or https."
      },
      "format": {
        "type": "string",
        "enum": ["markdown", "html", "json"],
        "default": "markdown",
        "description": "Output format: markdown, html, or json."
      },
      "links": {
        "type": "boolean",
        "default": false,
        "description": "Include extracted page links when supported."
      },
      "image_links": {
        "type": "boolean",
        "default": false,
        "description": "Include extracted image links when supported."
      }
    },
    "required": ["urls"]
  }
}

Comparison with the Official Integration

While TinyFish provides an official MCP integration using OAuth 2.1 for secure authentication (which requires a browser-based flow for initial setup), this implementation uses a single TinyFish API Key. This makes it better suited for:

• Headless Environments: Ideal for servers or environments where no web browser is available.
• Free Access: Optimized specifically for usage with the TinyFish Free Access API.

Learn more about the official integration here.

Prerequisites

• Python >= 3.11
• An MCP-compatible client

Installation

Using uv (Recommended)

For a clean installation as a standalone tool with isolated dependencies, use uv:

uv tool install .

Using pip

If you are already working in a virtual environment:

pip install .

Usage

Before running the server, set your TinyFish API Key as an environment variable.

Linux / macOS (bash, zsh):

export TINYFISH_API_KEY="<your tinyfish api key>"

Windows PowerShell:

$env:TINYFISH_API_KEY="<your tinyfish api key>"

API keys are obtained by logging in at https://agent.tinyfish.ai/. Once your API key is set, the server can be invoked via its command-line entry point:

tinyfish-search-fetch-mcp

You can optionally provide a Python logging configuration file. JSON files are loaded with logging.config.dictConfig; other extensions are loaded with logging.config.fileConfig. Ensure custom handlers write to stderr, not stdout, because stdout is reserved for MCP JSON-RPC messages.

tinyfish-search-fetch-mcp --log-config ./logging.json

Integration with Claude Desktop

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "tinyfish-search-fetch": {
      "command": "tinyfish-search-fetch-mcp",
      "env": {
        "TINYFISH_API_KEY": "<your tinyfish api key>"
      }
    }
  }
}

Note: If you have already defined TINYFISH_API_KEY in your shell environment (e.g. via ~/.bashrc, ~/.zshrc), the "env" block above is optional and can be omitted.

If you installed via pip in a virtual environment, ensure the command points to the correct executable path.

Troubleshooting

Empty search query error

If you see an error such as valueerror: query must not be empty, ensure the query parameter contains non-whitespace characters. Leading or trailing whitespace is automatically trimmed.

Invalid fetch format error

If you see an error such as valueerror: format must be one of: html, json, markdown, set format to markdown, html, or json.

Invalid URL scheme error

If you see an error such as valueerror: url scheme must be http or https, ensure the url parameter uses either http:// or https:// as the scheme.

Unsupported URL

If you see an error such as valueerror: url must include a host, the provided URL does not contain a valid hostname. Provide a full URL including domain (e.g. https://example.com).

Stdio fallback mode

In environments where FastMCP's default stdio wrapper hangs, set TINYFISH_MCP_THREAD_STDIO=1 to use the thread-based stdio fallback. This fallback is also selected automatically when CODEX_SANDBOX_NETWORK_DISABLED is truthy.

Logging privacy

The server logs search queries and fetch URLs to stderr by default. Avoid putting secrets in queries or URLs, or provide a custom --log-config that adjusts the log level or redacts messages.

Development

Local Installation

Clone and install this server in editable mode:

With pip:

git clone <repository-url>
cd tinyfish-search-fetch-mcp
pip install -e ".[dev]"

With uv:

git clone <repository-url>
cd tinyfish-search-fetch-mcp
uv pip install -e ".[dev]"

Running Tests

This project uses pytest. To run the test suite:

pip install -e ".[dev]"
python -m pytest

With uv, sync the default development dependency group first:

uv sync
uv run python -m pytest

Live tests exercise the real TinyFish Search/Fetch APIs. They require both network access and TINYFISH_API_KEY.

• If TINYFISH_API_KEY is not set, live tests are skipped.
• If CODEX_SANDBOX_NETWORK_DISABLED=1, live tests are skipped because outbound network access is unavailable.
• With network access and an API key, the live tests call all three MCP tools and cover parameter variants such as location, language, max_results, format, links, and image_links.

Coding Standards

Dependencies are intentionally version-bounded in pyproject.toml to reduce breakage from FastMCP and TinyFish SDK changes. The uv dev dependency group is included by default so uv run python -m pytest has pytest available; use uv run --no-dev ... for runtime-only checks. If you change dependency bounds or dependency groups, update uv.lock as well.

Use ruff for linting:

python -m ruff check src tests

License

This project is licensed under the MIT License - see the LICENSE file for details.