codex-search-mcp
This MCP server provides live web research, financial, weather, sports, and time utilities via CLI or MCP tools.
Web search: Search the web with queries and optional result limits, returning titles, URLs, and snippets.
Page extraction: Fetch readable content from URLs, open pages by reference, click numbered links, and search within pages.
Screenshot PDFs: Capture screenshots of PDF pages using reference IDs or URLs.
Image search: Search images with optional domain filters and recency bounds.
Finance: Look up quotes for equities, funds, crypto, and indexes (e.g., NVDA, BTC).
Weather: Get current conditions and forecasts by location with optional start date and duration.
Sports: Retrieve schedules and standings for leagues like NBA, EPL, NFL, MLB, and more.
World time: Resolve current time for a given UTC offset (e.g., +08:00, -05:00).
Authentication: Supports OAuth login, API keys, and custom base URL/proxy configuration.
CLI and MCP: Usable both as a command-line tool and as a stdio MCP server for AI assistants.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex-search-mcp search the web for the latest SpaceX Starship launch news"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@mintocha/codex-tools
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 loginThe 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-toolsOr 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 the web and return titles, URLs, and snippets |
| Extract cleaned markdown/text from a webpage URL |
| Look up quotes ( |
| Fetch current weather and multi-day forecasts |
| Look up schedules or standings ( |
| Resolve current time for an offset like |
| Search images with optional recency bounds |
| Interactive OAuth device flow saving to |
| Run the stdio MCP server (default when invoked without args) |
| 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.jsonLinux:
~/.config/Claude/claude_desktop_config.jsonWindows:
%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-toolsType:
commandCommand:
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 |
|
| JSON list of |
|
| Clean text/markdown for each requested URL |
|
| Page text positioned at the specified line |
|
| Target page text from following a numbered reference link |
|
| Matched pattern occurrences and surrounding context |
|
| JSON list of image search matches |
|
| Current market price, change, volume, and company details |
|
| Weather conditions and temperature forecast |
|
| Scores, upcoming fixtures, or current table |
|
| Current ISO and formatted time for the given offset |
Authentication order
The client checks credential sources in this order:
CODEX_API_KEYorOPENAI_API_KEYenvironment variables.~/.omp/agent/web.toml(extractsapi_keysandbase_urlif present).~/.codex/auth.json(created bynpx @mintocha/codex-tools loginor 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-toolsExpected 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 testLicense
MIT
Available Tools
11 toolsclick-linkC
Open the link link_id (numbered reference link) from previously opened page ref_id.
Inputs: ref_id (required), link_id (required).
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).
image-searchC
Query image search engine for a given query.
Inputs: query (required), domains, recency_days.
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.
web-searchA
REQUIRED live-web search for current or externally verifiable information, including benchmark scores, specifications, prices, news, documentation, and comparisons. Return source URLs, snippets, and clean results.
Inputs: query (required), max_results.
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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
One MCP URL for web search, page reading, pay-per-result data tools and a browser agent.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityBmaintenanceEnables 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.-
- AlicenseAqualityCmaintenanceEnables MCP-compatible clients to search the web and fetch HTTP/HTTPS pages as Markdown, returning result metadata such as titles, URLs, dates, relevance, and summaries.252 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.1Apache 2.0