F
licenseNot graded
qualityC
maintenanceEnables local document question-answering and retrieval via MCP, supporting multi-turn conversation, intent recognition, and tools for document search, Q&A, and summarization.
5
-
Binoculars Local MCP
by gauravsdama
This server provides a read-only local interface for running Binoculars zero-shot AI-text detection on supplied text.
binoculars_status: Reports local model readiness, selected profile, weight-hash verification, stdio transport, network-guard status, and calibration context.
binoculars_analyze_text: Accepts up to 100,000 characters of text and analyzes it with local observer/performer models.
Threshold modes: Choose
low-fpr(default, conservative about AI labels) oraccuracy(broader screening).Offline/secure operation: Runs over stdio, blocks network connections, forces offline model loading, and requires verified local SafeTensors weights.
Output: Returns score, threshold, mode, label, model profile, and calibration summary to aid interpretation.
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., "@Binoculars Local MCPAnalyze this text for AI-generated content: 'The committee reached a consensus after lengthy deliberation.'"
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.
Binoculars Local MCP
This repository is a local, security-focused derivative of Binoculars, the zero-shot AI-text detection method introduced in Spotting LLMs With Binoculars. The upstream authors created the scoring method and original implementation. This project adds a read-only MCP interface, offline model loading, process-level network blocking, a compact local model profile, and profile-specific calibration.
The detector returns a statistical signal, not proof that a person or model wrote a passage. It should not be the sole basis for grading, discipline, employment decisions, accusations, or other consequential action.
Local security boundary
MCP transport is
stdio; the server does not listen on a port.The MCP process blocks TCP and UDP connections while leaving local Unix-domain sockets available to libraries.
Hugging Face and Transformers offline modes are forced on.
Model arguments must resolve to existing local directories; remote model IDs are rejected.
Loads require
local_files_only=True,trust_remote_code=False, and SafeTensors weights.The compact profile verifies the SHA-256 digest of each model weight file before reporting readiness or loading the detector.
Both tools are read-only and declare
openWorldHint=false.Input is limited to 100,000 characters, and the compact profile analyzes at most 256 tokens.
Installing Python packages may contact a package index. Model acquisition is a separate explicit step. Once configured, the server requires local model files and is designed to run without application network access.
Related MCP server: shutter-mcp
Install
Python 3.11 through 3.13 is supported. This checkout uses Python 3.12 with uv:
On a Mac, begin with the optional setup helper. Its default mode only reports macOS,
processor, memory, disk, Python, and uv readiness:
./scripts/setup_macos.shDependency installation and model acquisition remain separate choices:
./scripts/setup_macos.sh --install
./scripts/setup_macos.sh --download-models
source .models/env.zshThe second command explains the download before it starts, fetches the two pinned model
revisions, verifies each SafeTensors weight file, and writes an ignored local environment file.
Use --yes only after reviewing the requested operation.
For manual setup:
uv sync --python python3.12 --extra dev --lockedModel weights stay outside Git under .models/. Point the server at compatible local directories:
export BINOCULARS_PROFILE=qwen2.5-0.5b
export BINOCULARS_OBSERVER_MODEL=/path/to/qwen2.5-0.5b-base
export BINOCULARS_PERFORMER_MODEL=/path/to/qwen2.5-0.5b-instructWithout both model directories, the MCP server can still start, but binoculars_status reports that analysis is not ready.
Compact model profile
The qwen2.5-0.5b profile pairs Qwen2.5-0.5B with Qwen2.5-0.5B-Instruct. Their SafeTensors weights use about 1.9 GB together, substantially less than the two 7B models in the original configuration. Repository revisions, file hashes, thresholds, token limit, and the calibration summary are pinned in binoculars/profiles.py.
This compact profile was calibrated on 360 local texts and evaluated on a separate 240-text holdout derived from CC-News, CNN, and PubMed human/Falcon samples. The calibration corpus is not distributed with this repository. On that holdout, accuracy mode reached 88.3%. Conservative mode measured a 2.5% human false-positive rate and a 60.0% machine true-positive rate. This is a limited local benchmark, not a general performance guarantee and not the original paper's evaluation.
MCP tools
binoculars_status
Reports model readiness, selected profile, weight-hash checks, stdio transport, the active network-guard probe, and calibration context. Call it before analysis.
binoculars_analyze_text
Accepts text and an optional threshold mode:
low-fpris the default and is more conservative about AI-generated labels.accuracyprovides the profile's broader screening threshold.
The result includes the score, threshold, mode, label, model profile, and calibration summary. Lower scores indicate a stronger AI-generated signal under the configured threshold. Samples of roughly 200-300 words are generally more useful than very short passages.
Run and verify
Start the stdio server:
.venv/bin/binoculars-mcpAvailable project checks are:
.venv/bin/pytest -q
.venv/bin/ruff check binoculars tests
.venv/bin/bandit -q -c pyproject.toml -r binoculars
.venv/bin/pip-auditInspect a Codex registration with:
codex mcp get binoculars-local
codex mcp listInference for a local stdio server uses the machine's MPS or CPU resources. It does not use hosted Codex inference compute.
Local performance
Measurements below were taken on a 24 GB M4 Pro MacBook Pro with macOS 26.6.2. Each run loaded both pinned Qwen2.5-0.5B models and analyzed the same 1,196-character passage six times.
Device | Model load | First call | Repeated median | Repeated p95 | Memory |
MPS | 1.54 s | 0.31 s | 0.159 s | 0.159 s | 538 MiB peak RSS; 3,123 MiB MPS driver |
CPU | 1.73 s | 1.25 s | 0.346 s | 0.425 s | 5,234 MiB peak RSS |
The first uncached MPS process took 2.85 seconds to load the models and 2.21 seconds for its first call. Later runs benefited from operating-system file caches. Reproduce the measurement with:
uv run python scripts/benchmark_local.py --device mps --iterations 6
uv run python scripts/benchmark_local.py --device cpu --iterations 6Limitations
Binoculars signals are weaker on short, non-English, heavily quoted, or memorized text. Results also depend on the selected observer/performer models and calibration data. Report the score, threshold, mode, and profile together; do not translate one label into certainty about authorship.
Attribution
The Binoculars score and original implementation are by Abhimanyu Hans, Avi Schwarzschild, Valeriia Cherepanova, Hamid Kazemi, Aniruddha Saha, Micah Goldblum, Jonas Geiping, and Tom Goldstein. See the paper, upstream repository, and preserved license.
The local MCP runtime, offline and network guards, compact profile configuration, weight verification, security tests, and local calibration are Gaurav Dama's derivative work. The underlying detection method remains the upstream authors' work.
Available Tools
2 toolsbinoculars_analyze_textBRead-onlyIdempotent
Assess text using pre-existing local models; never proof of authorship.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context beyond those: the analysis is not proof of authorship and uses local models, which is a useful limitation for an agent to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every element earns its place: the action, the local-model context, and the critical limitation about authorship.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with annotations, schema-provided parameter descriptions, and an output schema, the description covers the main non-obvious context. The absence of explicit usage guidance versus alternatives is the main gap preventing a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description gives no parameter-level guidance for `text` or `mode`. With schema description coverage at 0%, the description was expected to compensate; it does not. The input schema itself documents the parameters well, which prevents a score of 1.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Assess text using pre-existing local models.' It is semantically distinct from the sibling `binoculars_status`, though it does not explicitly name that sibling or draw a contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance or exclusions beyond the caution 'never proof of authorship.' It does not mention alternatives or describe situations where this tool should be preferred, so the agent must infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
binoculars_statusARead-onlyIdempotent
Check local model configuration and confirm the network guard is active.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by naming the two specific things being checked—model configuration and network guard activity—which goes beyond the title and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence with no filler. The main action and the two status aspects are front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only status check with annotations and an output schema, the description is complete enough. It clearly states what the tool checks, and there is no missing information required for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the baseline of 4 applies. The description correctly focuses on the behavior rather than parameter details, since there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Check local model configuration and confirm the network guard is active.' This clearly identifies a status/readiness check and distinguishes it from the sibling binoculars_analyze_text, which is a text-analysis operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for confirming local readiness, but it does not explicitly state when to use it versus binoculars_analyze_text or give any exclusion guidance. The sibling name suggests a different purpose, but the description leaves the selection decision mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.0- First observed
binoculars_analyze_text - First observed
binoculars_status
TDQS
A3.9/5.0
Scored across 2 tools
Disambiguation5/5
Only two tools exist, and their purposes are completely distinct: one checks system status, the other performs text analysis. There is no overlap or ambiguity between them.
Naming Consistency4/5
Both tools share the 'binoculars_' prefix and use lowercase snake_case, which is consistent. However, 'binoculars_status' is a noun rather than a verb_noun pattern, while 'binoculars_analyze_text' follows the verb_noun structure.
Tool Count3/5
With only two tools, the set feels thin even though each tool serves a clear purpose. For the server's narrow scope of text analysis and status checking, the count is borderline but acceptable.
Completeness5/5
The tool surface covers the two core functions: checking configuration/status and analyzing text with local models. No obvious missing operations are apparent given the server's stated purpose.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Free OpenAI-compatible inference with signed provenance receipts and 3 focused MCP tools.
Paid remote MCP for LLM security scans, jailbreak checks, analytics, checkout, and readiness.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA local, read-only MCP server that lets AI agents inspect and analyze photo libraries by scanning files, aggregating EXIF stats, finding duplicates, scoring blur, and generating cull reports without uploading any data.MIT
- AlicenseNot gradedqualityBmaintenanceProvides a local, read-only MCP server that scans untrusted text for prompt-injection and returns an allow/review/block decision with evidence. It runs entirely on-device with no network requests and redacts sensitive strings by default.50 npmMIT
- AlicenseAqualityBmaintenanceProvides local, deterministic scoring and detailed auditing of text for AI-writing patterns via two read-only tools, with no network calls or language models.428 npm2MIT