osint-mcp

An MCP server for OSINT workflows, powered by local knowledge from writeups/. Implementation stack: hono + @hono/mcp.

Install from npm

npm i -g osint-mcp

or run it directly:

npx -y osint-mcp

Setup

bun install
bun run dev

Git Hooks

Install the repository hooks:

bun run hooks:install

Current policy:

• pre-commit runs bun run typecheck only

Codex MCP (One Command)

Register this server in Codex with a single command:

codex mcp add osint-mcp-local -- bun --cwd "$(pwd)" run mcp:stdio

If you run the command outside this repository, replace "$(pwd)" with the absolute path to this project.

If you use the published npm package:

codex mcp add osint-mcp -- npx -y osint-mcp

Verify registration:

codex mcp list

Start Modes

# HTTP mode (default)
bun run dev:http
bun run start:http

# Command mode (stdio transport for MCP clients)
bun run dev:stdio
bun run start:stdio
bun run mcp:stdio

Build / Start

bun run build
bun run start

Checks

bun run typecheck
bun run test

After startup:

• GET /health
• ALL /mcp

Implemented MCP tools

• search_past_writeups
  • Full-text search over writeups/**/README.md and return top matching hints
• list_frequent_domains_in_writeups
  • Aggregate frequently referenced domains from writeups
• duckduckgo_search_api
  • Query DuckDuckGo Instant Answer API (no API key required)
• wayback_cdx_lookup
  • Query Wayback Machine CDX API snapshots (supports timeoutMs for heavy wildcard queries)
• jina_fetch_url
  • Fetch page text through https://r.jina.ai/
• twstalker_profile_lookup
  • Fetch Twstalker profile timeline via r.jina.ai and extract recent post snippets
• capsolver_create_and_poll
  • Create a CapSolver task and poll until completion (apiKey passed as input)
• yandex_image_search_scrape
  • Scrape Yandex image search results without an API key
• archive_today_lookup
  • Fetch archive.today/archive.md timemap entries
• domain_recon_bundle
  • Bundle DNS / RDAP / crt.sh / whois / optional Shodan lookups
• extract_metadata_from_media
  • Extract metadata from local or remote media (exiftool/ffprobe/exifr)