PROJECT ARGUS — Open-Source Intelligence Fusion Platform & MCP Server

UNCLASSIFIED // OPEN SOURCES ONLY // FOR RESEARCH & EDUCATION

ARGUS pulls 71 live, public intelligence feeds across 12 disciplines into one local SQLite store, renders them on an interactive 3D WebGL globe, and exposes the whole thing to LLM agents through a Model Context Protocol (MCP) server with 17 typed tools — so Claude, Gemini, or any MCP host can run multi-hop reconnaissance over real-time global data instead of guessing from a training cutoff.

Everything runs on your own machine. The server binds to 127.0.0.1 only, the database and credential vault live outside the source tree, and 60 of the 71 collectors need no API key at all.

What's inside

The 12 disciplines

* needs a key — attach it in the Keys tab. Everything else works out of the box.

Related MCP server: Darknet MCP

Quick start

Requirements: Linux or macOS, Python 3.10+, ~500 MB disk (OpenCV + NumPy).

git clone https://github.com/Sockshare/project-argus.git
cd project-argus
./run.sh

run.sh creates a local .venv, installs requirements.txt into it, and opens http://127.0.0.1:8087. First launch takes a minute; after that it's instant.

Manual equivalent:

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python server.py

First five minutes

1. HOME — the globe. Toggle layers on the left, click any dot for its source URL and raw record.

2. Keys → "Auto-provision" — attaches keyless open-bridges for every slot so all collectors run. Paste real keys later if you want Shodan, Google Earth tiles, ACLED, etc.

3. Ask AI — draw a box or pick a country, ask for a SITREP. With no LLM key attached you get the deterministic offline analyst; attach a Gemini/Anthropic/OpenAI key for tool-calling reasoning.

4. Cameras — public DOT/maritime/weather cams with viewshed cones; optional on-frame face screening against your local watchlist.

5. Cyber Check — IP / CVE / domain dossier with zero keys (InternetDB, abuse.ch, KEV, EPSS).

Using ARGUS as an MCP server

python3 mcp_server.py --list            # print the 17 tools
python3 mcp_server.py --print-config    # ready-to-paste Claude Desktop / Gemini CLI snippets

Claude Desktop (claude_desktop_config.json) or Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "argus": {
      "command": "/ABSOLUTE/PATH/project-argus/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/project-argus/mcp_server.py"]
    }
  }
}

Tools: query_region, search_events, get_event, domain_summary, country_profile, stats, lookup_ip, lookup_cve, search_sanctions, stac_search, aircraft_near, quakes_near, geocode, reverse_geocode, list_collectors, run_collector, compress_region.

A typical agent pivot: suspicious domain → lookup_ip (ASN, abuse score, open ports) → search_sanctions on the registrant → aircraft_near / query_region around the hosting PoP → compress_region for a digest the model can reason over in one turn.

Configuration

Everything is optional. Keys can be set as environment variables (see .env.example) or pasted into the Keys tab, which stores them in ~/.config/osint_tester/vault.json with 0600 permissions.

Run a single collector from the CLI:

.venv/bin/python -m osint.collectors usgs_quakes

Project layout

project-argus/
├── server.py              FastAPI app: REST API, SSE stream, static UI
├── mcp_server.py          Stdio MCP server (JSON-RPC 2.0)
├── run.sh                 One-command launcher (creates .venv)
├── requirements.txt
├── osint/
│   ├── config.py          Paths, ports, the 12 disciplines
│   ├── store.py           SQLite + FTS event store
│   ├── scheduler.py       Collector scheduling, concurrency, TTL
│   ├── cache.py           HTTP cache + rate limiting
│   ├── vault.py           Credential vault + keyless "open bridges"
│   ├── keytests.py        Live key validation per provider
│   ├── tools.py           The 17 analyst/MCP tools
│   ├── compress.py        Selection → token-budgeted grounding context
│   ├── agent.py           LLM analyst (Anthropic / Gemini / OpenAI / offline)
│   ├── biometrics.py      YuNet + SFace local face engine
│   ├── godseye.py         Cameras, cyber deep-scan, alerts, link graph
│   ├── geo.py             Geocoding, MGRS/UTM, country reference data
│   ├── collectors/        71 collectors grouped by discipline
│   └── data/
│       ├── models/        ONNX face models (OpenCV Zoo, Apache-2.0)
│       └── samples/       Demo images for BIOMINT (see docs/SAMPLES.md)
├── static/                index.html, globe + UI JS, CSS (no build step)
├── deploy/                Dockerfile, docker-compose, nginx, PostGIS init
└── docs/                  Architecture, API contracts, collector rules, UI specs

Developer docs: docs/BACKEND_SPEC.md · docs/API_CONTRACT.md · docs/AGENT_SPEC.md · docs/COLLECTOR_RULES.md (how to add a collector in ~40 lines).

Privacy, safety & responsible use

• Local by default. Loopback bind, local SQLite, local face models. Data only leaves your machine when a collector calls its public upstream API, or when you attach a cloud LLM key and press Ask AI.

• Open sources only. Every collector targets a public, documented endpoint and honours its rate limits. Nothing here bypasses authentication or scrapes behind logins.

• Biometrics stay on-device. The watchlist is a local SQLite table you populate yourself. Demo subjects are AI-generated or public-domain US Government photos — see docs/SAMPLES.md. Facial recognition is regulated in many jurisdictions; it is your responsibility to use this feature lawfully.

• No secrets in the repo. Keys live in the vault or env vars. Please keep it that way in PRs.

This is a research and portfolio project, not a certified intelligence product. Verify anything important against the primary source linked on every event.

License

MIT — see LICENSE. Face models © OpenCV Zoo (Apache-2.0). Upstream data is subject to each provider's own terms.