Skip to main content
Glama
codex-search-mcp

codex-search-mcp

by MintOcha

@mintocha/codex-tools

npm version license

An MCP server and command-line tool for web search, page extraction, finance quotes, weather forecasts, and sports scores, backed by OpenAI's reversed Codex web endpoints.

Runs directly as an MCP server via stdio for Claude Desktop, Cursor, Windsurf, and Oh My Pi, or as a standalone terminal CLI for ad-hoc queries.

Quick start

Log in once

If you use a ChatGPT or Codex subscription, authenticate via the device code flow:

npx @mintocha/codex-tools login

The CLI prints a verification link and a one-time code. Once approved in your browser, the OAuth tokens are saved to ~/.codex/auth.json (chmod 600) and refreshed automatically before expiration.

Run commands directly

# Web search
npx @mintocha/codex-tools search "TypeScript 5.8 release notes"

# Fetch readable webpage text
npx @mintocha/codex-tools fetch "https://nodejs.org"

# Market quotes
npx @mintocha/codex-tools finance NVDA
npx @mintocha/codex-tools finance BTC crypto

# Weather
npx @mintocha/codex-tools weather "Tokyo" --days 3

# Sports scores and schedules
npx @mintocha/codex-tools sports nba standings
npx @mintocha/codex-tools sports epl schedule --team "Arsenal"

# UTC time
npx @mintocha/codex-tools time "+08:00"

Append --json to any command for structured JSON output.

Run as an MCP server

Start the stdio transport directly:

npx -y @mintocha/codex-tools

Or install globally to keep codex-tools on your PATH:

npm install -g @mintocha/codex-tools
codex-tools search "Postgres 17 changes"

Related MCP server: Qianxv-search-mcp

CLI reference

Command

Description

search <query> [--max <n>]

Search the web and return titles, URLs, and snippets

fetch <url> [--line <n>]

Extract cleaned markdown/text from a webpage URL

finance <ticker> [type]

Look up quotes (equity, fund, crypto, index)

weather <location> [--days <n>]

Fetch current weather and multi-day forecasts

sports <league> [type]

Look up schedules or standings (nba, epl, nfl, mlb)

time <utc_offset>

Resolve current time for an offset like +08:00 or -05:00

image-search <query> [--days <n>]

Search images with optional recency bounds

login

Interactive OAuth device flow saving to ~/.codex/auth.json

server

Run the stdio MCP server (default when invoked without args)

--help

Show command list and options

MCP client configuration

Add @mintocha/codex-tools to your client configuration file. If you already ran npx @mintocha/codex-tools login or have an existing ~/.codex/auth.json, you do not need to pass an API key in the environment.

Claude Desktop

File locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codex-tools": {
      "command": "npx",
      "args": ["-y", "@mintocha/codex-tools"]
    }
  }
}

If authenticating with an API key instead of OAuth:

{
  "mcpServers": {
    "codex-tools": {
      "command": "npx",
      "args": ["-y", "@mintocha/codex-tools"],
      "env": {
        "CODEX_API_KEY": "your_key_here"
      }
    }
  }
}

Cursor

Under Settings > Features > MCP > Add New MCP Server:

  • Name: codex-tools

  • Type: command

  • Command: npx -y @mintocha/codex-tools

Windsurf

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codex-tools": {
      "command": "npx",
      "args": ["-y", "@mintocha/codex-tools"]
    }
  }
}

Oh My Pi (OMP)

In ~/.omp/agent/mcp.toml:

[mcpServers.codex-tools]
command = "npx"
args = ["-y", "@mintocha/codex-tools"]

Available tools

When connected as an MCP server, the following tools are exposed over JSON-RPC:

Tool

Parameters

Output

web-search

query (string, required), max_results (integer, 1–25, default 10)

JSON list of { title, url, snippet } objects

fetch

urls (string array, required)

Clean text/markdown for each requested URL

open-page

ref_id (string, required), lineno (integer, optional)

Page text positioned at the specified line

click-link

ref_id (string, required), link_id (integer, required)

Target page text from following a numbered reference link

find-in-page

ref_id (string, required), pattern (string, required)

Matched pattern occurrences and surrounding context

image-search

query (string, required), recency_days (integer), domains (string array)

JSON list of image search matches

finance

ticker (string, required), asset_type (equity | fund | crypto | index)

Current market price, change, volume, and company details

weather

location (string, required), start_date (string), duration_days (integer)

Weather conditions and temperature forecast

sports

league (string, required), fn (schedule | standings), team (string)

Scores, upcoming fixtures, or current table

world-time

utc_offset (string, required, e.g. +08:00 or -05:00)

Current ISO and formatted time for the given offset

Authentication order

The client checks credential sources in this order:

  1. CODEX_API_KEY or OPENAI_API_KEY environment variables.

  2. ~/.omp/agent/web.toml (extracts api_keys and base_url if present).

  3. ~/.codex/auth.json (created by npx @mintocha/codex-tools login or the Codex CLI; auto-refreshes expired access tokens).

To route requests through a custom proxy:

export CODEX_BASE_URL="https://litellm.v-rail.org/v1"

Testing over stdio

You can test the server locally with an initialize JSON-RPC handshake:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"tester","version":"1.0.0"}}}' | npx -y @mintocha/codex-tools

Expected reply:

{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"codex-tools","version":"1.1.0"}},"jsonrpc":"2.0","id":1}

Development

git clone https://github.com/MintOcha/codex-tools.git
cd codex-tools
npm install
npm run build
npm test

License

MIT

Available Tools

11 tools
fetchC

Fetch readable page content for given URLs using Codex native page extraction.

Inputs: urls (required).

financeC

Look up financial quotes for a given ticker (type: equity, fund, crypto, index).

Inputs: ticker (required), market, asset_type.

find-in-pageC

Find text pattern in page indicated by ref_id or URL.

Inputs: ref_id (required), pattern (required).

open-pageB

Open the page indicated by ref_id or URL and position viewport at line lineno.

Inputs: ref_id (required), lineno.

screenshot-pdfC

Take a screenshot of page pageno (0-indexed) indicated by ref_id or URL (works on PDFs).

Inputs: pageno (required), ref_id (required).

sportsB

Look up sports schedules and standings (league: nba, wnba, nfl, nhl, mlb, epl, ncaamb, ncaawb, ipl; fn: schedule or standings).

Inputs: league (required), fn, team.

weatherC

Look up weather forecast for location (e.g. 'City, Country').

Inputs: location (required), start_date, duration_days.

world-timeB

Get current time for UTC offset (e.g. '+08:00' or '-05:00').

Inputs: utc_offset (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    The lookup tools (finance, weather, sports, world-time) are clearly distinct from each other and from the search tools. The browsing cluster (web-search, fetch, open-page, click-link, find-in-page, screenshot-pdf) is mostly separable by action, but fetch vs open-page overlap in that both take a URL and return page content, which could cause misselection.

    Naming Consistency3/5

    Verbs use a hyphenated verb_noun pattern (web-search, open-page, click-link, find-in-page, image-search), but there are deviations: bare 'fetch', the hyphen-only 'screenshot-pdf', and noun-only tools (finance, weather, sports, world-time). Readable but not a single predictable convention.

    Tool Count4/5

    11 tools is within a reasonable range for a combined web-search and lookup server. The six browsing tools feel somewhat heavy for page interaction, but each covers a distinct capability and nothing is clearly redundant.

    Completeness4/5

    Core search and browsing coverage is solid: search, content fetch, open, link navigation, in-page find, screenshot, and image search. The domain lookups round out common queries; there are minor gaps (e.g. no news/translation tools) but these are workable via web-search.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to perform keyless web searches, extract fully rendered pages into clean Markdown, and automate a shared Chrome browser through page navigation, clicking, typing, reading, screenshots, and backtracking—all without API keys.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to run local web searches with automatic failover across multiple search providers and to extract public web pages as titles and Markdown content, using circuit breaking and key-redacted logging.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents and LLM apps to run live web searches and fetch public web pages as Markdown, returning structured search results and page content through MCP clients.
      1
      Apache 2.0