Research Oyster

Research Oyster is a local, source-agnostic research engine for Claude Code, Codex, and other MCP-compatible AI hosts. Give it an ordinary research brief; it turns the brief into questions and platform-specific searches, stores cited evidence in PostgreSQL, tracks coverage gaps, and returns a resumable dossier.

The repository also includes Gaming Culture Pulse, a browser control center and reporting workflow built on the same collection foundation.

The optional Research Oyster Capture browser extension adds supervised evidence capture for Discord, X, Twitch chat, Reddit, and other pages a researcher can already access. Candidates stay in the extension until the user explicitly approves them; approved excerpts enter the original research job and dossier.

What a user gives Oyster

Only a subject and the decision the research should support are required:

Research Kirkland Italian sparkling mineral water for a US Christmas 2026 campaign. Find consumer tensions, competitor activity, and three creative opportunities.

Audience, market, time period, required platforms, exclusions, and output format are optional. Oyster recommends relevant sources and creates source-specific queries. It does not force Twitch or Discord into research where they add no value.

Related MCP server: surveyHelper

Fastest setup on macOS

1. Download or clone this repository.

2. Double-click Install Gaming Pulse.command.

3. Follow the Homebrew prompt if it appears, then run the installer again.

4. Wait for the local control center to open.

5. Click Setup and add only the source credentials you want.

6. Double-click Attach Research Oyster.command.

7. Restart Claude Code or Codex.

8. Ask your AI host: “Use Research Oyster to research …”

To add supervised browser capture, open chrome://extensions or edge://extensions, enable Developer mode, choose Load unpacked, and select the repository's browser_extension folder. In Oyster's control center, create a one-time pairing code and enter it in the extension settings.

The database is required. Every external connector is optional. The installer creates a local PostgreSQL database and isolated Python environment without replacing an existing .env file or database.

For the complete beginner walkthrough, credential instructions, manual Linux setup, verification, and troubleshooting, read docs/SETUP.md.

Source support

No credential is required unless the corresponding source is selected. API/provider charges are separate from Oyster.

How to use it

In your MCP-compatible AI host:

Use Research Oyster to compare how US college students discuss affordable gaming laptops across Reddit, X, Twitch, and technology press. Focus on purchase barriers from the last six months. Give me a cited opportunity map and clearly identify unavailable sources.

The host should create a job, inspect connector readiness, gather and store evidence, inspect the final dossier, and synthesize with direct citations. Jobs persist locally and can be resumed later.

See docs/USAGE.md for prompt templates, individual MCP tools, the browser workflow, and command-line examples.

Manual quick start

Requirements: Python 3.11+, PostgreSQL 15+, and Git.

git clone https://github.com/zandemha2025/research-oyster.git
cd research-oyster
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
createdb gaming_pulse
python main.py migrate

Attach using the absolute path returned by pwd:

codex mcp add research-oyster -- "$(pwd)/research-oyster-mcp"
claude mcp add --scope user research-oyster -- "$(pwd)/research-oyster-mcp"

Run the browser control center with:

./Open\ Gaming\ Pulse.command  # macOS
# or
.venv/bin/python control_center.py

Verification

.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -q
.venv/bin/python tests/postgres_acceptance.py
.venv/bin/python tests/research_postgres_acceptance.py

The release was validated against 93 user stories. The local audit found and fixed nine logistical, security, data-quality, and UX defects, then passed all 93 post-fix behaviors.

Important boundaries

Research Oyster is a collection and evidence-management tool, not a license to access restricted data. Use only public material or systems you are authorized to access. Follow platform terms, API terms, robots directives where applicable, privacy and employment rules, copyright law, and local consent requirements. Do not use it to bypass authentication, rate limits, access controls, bans, or technical protections. Do not collect sensitive personal data merely because it is technically visible.

Generated results can be incomplete, outdated, biased, or incorrect. Verify material claims and obtain professional advice before legal, medical, employment, financial, safety, or similarly consequential decisions. Read the full DISCLAIMER.md before use and SECURITY.md before exposing or deploying the software.

Security model

The included server uses local MCP stdio and the browser control center/capture API binds to 127.0.0.1:8765. The extension pairs with a single-use code and a revocable token bound to its extension origin. Credentials are stored in the local .env file and are excluded from Git; the extension never receives them. This is not a production multi-user hosted service. Internet exposure requires authentication, tenant isolation, encrypted secret storage, rate limiting, audit logging, retention controls, and isolated collection workers.

License

MIT. See LICENSE. Third-party services, APIs, content, and Actors retain their own terms and licenses.