obsify MCP란?
obsify은(는) MCP server입니다. 원시 PII를 노출하지 않고 스키마, 합성 트윈(synthetic twins), 로컬 마스킹 연산을 제공하여 AI 어시스턴트가 민감한 파일을 처리할 수 있도록 합니다.
프로젝트 README에서 생성된 요약
obsify MCP server 정보
기밀 문서를 다루는 개발자는 obsify를 사용하여 원시 개인정보(PII)를 노출하지 않고도 AI 어시스턴트가 민감한 데이터를 추론하도록 할 수 있습니다. compute-to-data 방식을 사용하여, 모델은 스키마, 합성 트윈 또는 마스킹된 결과와만 상호작용하며 파일의 실제 내용은 로컬 경계 내에 유지되도록 서버가 보장합니다. 이는 stdio를 통해 서브프로세스로 실행되는 로컬 MCP server를 통해 구현되며, 런타임 시 원격 호스팅이나 네트워크 호출이 필요하지 않습니다.
서버는 값을 노출하지 않고 데이터 유형을 식별하는 scan_pii, Excel 워크북의 구조를 유지하면서 가짜 데이터를 생성하는 make_synthetic_twin, 로컬 샌드박스에서 실제 파일에 대해 모델이 작성한 코드를 실행하는 run_on_real과 같은 특정 도구를 제공합니다. PDF, Excel, Word 문서를 지원하며, 정규식, 체크섬 및 로컬 NER을 사용하여 ABN 또는 TFN과 같은 호주 엔티티뿐만 아니라 클라우드 키 및 데이터베이스 연결 문자열을 감지합니다. 사용자는 레이블 기반 매니페스트를 사용하여 결정론적 라우팅 레이어를 설정함으로써 어시스턴트가 원시 데이터를 피해야 하는 시점을 강제할 수 있습니다.
활용 사례
- 1행 데이터 유출 없이 스프레드시트 분석AI가 실제 민감한 값 대신 스키마를 확인하여 재무 장부의 구조를 이해할 수 있습니다.
- 2현실적인 가짜 데이터를 활용한 코드 개발개발자는 실제 구조를 유지하면서 가짜 값을 사용하는 Excel 워크북의 합성 버전을 사용하여 어시스턴트가 처리 로직을 작성하도록 할 수 있습니다.
- 3민감한 인증 정보 파일 감사파일을 처리하기 전에 폴더에 클라우드 키, API 토큰 또는 개인 키가 포함되어 있는지 자동으로 감지합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
obsify MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 obsify MCP 설치
$ claude mcp add obsify -- uvx obsifyCursor에 obsify MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"obsify": {
"command": "uvx",
"args": [
"obsify"
]
}
}
}VS Code에 obsify MCP 설치
.vscode/mcp.json
{
"servers": {
"obsify": {
"type": "stdio",
"command": "uvx",
"args": [
"obsify"
]
}
}
}VS Code CLI에 obsify MCP 설치
$ code --add-mcp '{"name":"obsify","type":"stdio","command":"uvx","args":["obsify"]}'Claude Desktop에 obsify MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"obsify": {
"command": "uvx",
"args": [
"obsify"
]
}
}
}Codex에 obsify MCP 설치
$ codex mcp add obsify -- uvx obsifyCodex config.toml에 obsify MCP 설치
~/.codex/config.toml
[mcp_servers.obsify] command = "uvx" args = ["obsify"]
Gemini CLI에 obsify MCP 설치
$ gemini mcp add -s user obsify uvx -- obsifyGemini settings.json에 obsify MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"obsify": {
"command": "uvx",
"args": [
"obsify"
]
}
}
}자동 검사
2026년 11월 15일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능formative-sum41/obsify is public and reachablegithub.com/formative-sum41/obsify ↗통과
- 패키지가 이 저장소를 소스로 명시obsify names formative-sum41/obsify as sourcepypi.org/project/obsify/ ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for obsifypypi.org/project/obsify/ ↗통과
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-08-20github.com/formative-sum41/obsify ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from obsify통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음80 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기obsify
Let an AI assistant work on sensitive files without their raw values ever entering the model's context.
obsify is a local, deterministic MCP server. The frontier model reasons over shape — schemas, synthetic twins, masked feedback — while deterministic local code touches the substance and returns only masked, aggregated results. No LLM calls, no network at runtime: detection is regex + checksums + dictionaries + Presidio's local NER.
It ships with Australian entity support (ABN / ACN / TFN, checksum-validated), credential/secret detection (cloud keys, API tokens, private keys, DB connection strings), and a label-driven routing layer that makes "when should the assistant avoid raw data" a deterministic, enforced decision rather than a judgement call.
Honest scope:
run_on_realexecutes model-written code in a best-effort local sandbox and masks its output best-effort. It is not a jail. ReadSECURITY.mdbefore pointing it at anything you cannot afford to leak. Return aggregates.
Why
Feeding confidential documents to a hosted LLM means the substance leaves your perimeter. The usual answers are "don't use the LLM" or "trust the provider." obsify takes a third path — compute-to-data: bring the code to the data, not the data to the model.
- The model sees the schema of a spreadsheet, not its rows.
- The model develops against a synthetic twin (faked values, real structure).
- The model's analysis code runs locally; only masked, aggregated output returns.
The frontier model's reasoning is preserved. Only its eyes on raw values are removed.
Tools
| Tool | What it does | Returns |
|---|---|---|
scan_pii(path) |
Scan a file/folder for PII | Types, locations, counts — never values |
make_synthetic_twin(path, out) |
Faithful fake of an Excel workbook | Schema summary; twin written to out (values faked, leak-verified) |
run_on_real(code, data_path) |
Compute-to-data: run your code locally against the real file (bound to DATA_PATH) |
Only PII-masked, size-capped stdout/stderr — return aggregates |
redact_text(text) |
Mask PII in a string to <TYPE> tokens |
The redacted string |
verify_value_free(text, terms) |
Fail-closed check that text leaks none of terms (or their variants) |
{"value_free": bool} |
Supported documents: PDF (text + tables; complex-table fallback via obsify[tables]),
Excel .xlsx/.xlsm, and Word .docx (paragraphs + tables). Unreadable or unsupported files
are surfaced as explicit notes/blind spots, never silently dropped. (No OCR yet — scanned/image
pages are flagged as low-coverage, not transcribed.)
Known-entity masking (optional). Supply a local .obsify.entities list of names to hide;
scan_pii / redact_text deterministically catch them — and the suffix/abbreviation variants
NER misses (BRIGHTWATER HLDGS P/L for Brightwater Holdings Pty Ltd) — as KNOWN_ENTITY. The
list stays local and never enters the model's context. See docs/known_entities.md.
Demo
Poke at all five tools live against synthetic data with the official MCP Inspector:
python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcp
Call scan_pii on ./corpus_demo/ledger.xlsx and confirm it returns types / counts /
locations only — never values. See docs/verifying.md.
Try it — synthetic corpus
Generate a fake-but-realistic corpus (all synthetic; ABN/ACN/TFN are checksum-valid) spanning all three formats, then point a tool at it:
pip install "obsify[demo]" # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demo
It writes a multi-sheet Excel ledger (a numeric false-positive minefield), a PDF engagement
letter (prose + trial-balance table), and a DOCX audit memo (paragraphs + vendor table). Great
for kicking the tyres on scan_pii / make_synthetic_twin without touching real data.
Install & run as an MCP server
Requires Python 3.11+. obsify speaks MCP over stdio — the client launches it as a local subprocess; nothing is hosted remotely. Register it with any MCP-capable client (Claude Desktop, Claude Code, Cursor, VS Code, …) by adding one block to that client's config.
Recommended — zero-install via uvx:
{ "mcpServers": { "obsify": { "command": "uvx", "args": ["--from", "obsify", "obsify-mcp"] } } }
uvx fetches obsify from PyPI and runs it on demand — no permanent install. On first run,
obsify downloads the spaCy NER model (en_core_web_lg, ~560 MB) once and caches it; this
fetches a public model and sends no user data (set OBSIFY_AUTO_DOWNLOAD=0 to forbid it and
install the model yourself). Later runs are instant and fully offline.
Or install it (pip / pipx):
pipx install obsify # isolated, on PATH (or: pip install obsify)
Then point the client at the installed command:
{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }
Restart the client and the tools appear. Optional extras: obsify[tables] (complex-table PDF
fallback via camelot + Ghostscript), obsify[compute] (pandas, handy inside run_on_real code).
PATH gotcha (the #1 cause of "server won't connect"): the
commandmust resolve on the PATH the client sees. A GUI client may not share your venv's PATH. Fixes: useuvx/pipx(globally resolvable), or give an absolute path —"/path/to/.venv/bin/obsify-mcp"(macOS/Linux) or"C:\\path\\to\\.venv\\Scripts\\obsify-mcp.exe"(Windows).
From this repo (before it's on PyPI):
pip install "git+https://github.com/Formative-Sum41/obsify.git" # gets `obsify-mcp` + `obsify`
The routing layer — deterministic, not a judgement call
The hard part of "help me, but don't read the confidential file" is deciding when to protect. obsify moves that decision out of the model and into the environment:
.obsify.json— a label manifest classifying paths (public/confidential/restricted).obsify.guard(run aspython -m obsify.guard) — a PreToolUse guard that blocks a direct read of a labelled file (exit 2) and redirects the assistant toscan_pii/make_synthetic_twin/run_on_real.- A convention (in
CLAUDE.md) so the assistant prefers obsify before it even hits the guard.
Set it up with one command:
obsify init [--dir PATH] [--with-claude-md]
obsify init is non-destructive by design — it owns exactly one file and hands you snippets
for the rest:
.obsify.json— obsify owns this; init writes it (never overwritten without--force)..claude/settings.json— your file: init prints the PreToolUse hook block to paste, never edits it (it runs code, so registering it is your call).CLAUDE.md— your file: the convention is opt-in. Default prints it;--with-claude-mdappends a marker-wrapped, idempotent block that never clobbers your content.
Full convention: docs/obsify_routing.md.
How detection stays precise
- Checksum-validated identifiers. ABN/ACN/TFN candidates are proposed by regex and confirmed by their official checksums, so a random number is never reported as an identifier.
- Context-required IDs. A bare number is only accepted as an ABN/ACN/TFN when a label word ("TFN", "ABN", "BSB", …) is nearby — this kills the sequential-journal-ID false-positive flood on numeric ledgers.
- Letterless / NER-with-digit suppression. Pure numbers, amounts, dates and alnum codes are not flagged as names/orgs; real names, emails and addresses (which carry letters) are unaffected. Validated letterless PII stays exempt: checksum IDs (ABN/ACN/TFN/Medicare), Luhn cards, valid IPs, BSB-adjacent accounts, and phones (via context or phone shape) — while a decimal point still marks an amount, not a phone.
- Credentials, not just PII. Cloud keys (AWS/GitHub/Google/Slack/Stripe), JWTs, private-key
blocks and DB connection strings are flagged as
CREDENTIALby anchored patterns — vendor prefixes (AKIA…,ghp_…) or a keyword-gatedsecret = <value>, never entropy heuristics (which would flood on hex/base64 ledger columns). The wholeBEGIN…ENDprivate-key block is masked, not just its header, so no key body is left behind.
Measured accuracy
obsify ships a scored evaluation harness (eval/ — labelled synthetic corpus + answer key +
scorer against the shipping detector, plus an independent third-party cross-check). Headline
on the synthetic corpus: 100% recall on expected-detect items, 0 false positives on a
numeric FP-torture sheet (with a grouped-number guard), bare context-gated IDs correctly
suppressed. Independent cross-check vs Microsoft presidio-research: EMAIL/IBAN 100%, PERSON 94%.
The harness earned its keep — it found real defects, which were then fixed: credit cards and
phone numbers were being silently suppressed by the numeric-noise filter (now exempt via checksum
validation / phone shape), and Medicare, IP, date-of-birth, AU passport and driver-licence had no
recognizer (now added, checksum- or context-gated). Full method, numbers, and remaining documented
gaps (SWIFT/BIC, non-DOB dates): eval/README.md.
Tests
pip install -e ".[dev]"
pytest tests/ # or run any file directly: python tests/test_obsify.py
Thirteen suites (88 tests), run in CI on Linux + Windows / Python 3.11 + 3.12:
- mcp-protocol — launches the real server over stdio and speaks MCP to it (the same path a
client like Claude uses): confirms all five tools register with valid schemas and that calls
round-trip through JSON-RPC — including
scan_piireturning shape only, end to end. - checksums — anchored to externally-published ABN/ACN/TFN worked examples (valid and corrupted), which breaks the generator↔validator circularity.
- obsify / twin / redaction — the privacy invariants: shape-only output, leak-free twins, and a fail-closed self-check.
- precision — the false-positive suppressors kill numeric-ledger noise while keeping real names.
- credentials — the anchored secret patterns catch cloud keys / tokens / JWTs / private-key blocks / connection strings, while keyword-anchored generics stay precise on prose (no entropy).
- routing — the guard's block/allow classification and
obsify init's non-destructive contract. - corpus — the synthetic PDF+Excel+DOCX corpus end to end: per-format detection, DOCX paragraph+table extraction, and shape-only output across every format.
- evaluation — the scored harness as a regression gate (recall, suppression, FP-torture, gaps).
- robustness — graceful degradation: corrupt/oversized/empty/nested/unsupported inputs never crash and are always surfaced as notes.
- model / variants — first-run model auto-download logic; variant normalization behind
verify_value_free.
For interactive verification (MCP Inspector) and the live-client last-mile check, see
docs/verifying.md.
Related work
obsify is one of several MCP servers tackling "let an AI touch sensitive data safely" — they're mostly complementary, solving the same problem from different ends. Worth knowing where each fits:
| Tool | Approach | Best for |
|---|---|---|
| obsify | Detection + shape-isolation: the model sees only shape, synthetic twins and masked aggregates — never the values (real or faked) | Messy, unstructured docs (PDF/Excel/DOCX) where you can't enumerate PII up front; strict value isolation; enforcement of when to protect |
| cloakbox | Policy-driven pre-sanitization: tokenize a database into a de-identified copy the model queries freely | Known, structured schemas where you want rich analytics (joins/aggregations) on a referentially-intact clean copy |
| redact-mcp | Reversible obfuscation proxy: the model works on consistent fakes; a proxy tool round-trips real API calls | Pentest workflows and secrets, where the model must operate on realistic data and you restore reals later |
| cms-ai | Enterprise redaction service: Presidio + spaCy behind REST/MCP, multi-language, scalable | A hosted, multi-language redaction API with a UI and horizontal scale |
Where obsify is distinct: it's the only one of these where the model gets neither raw values nor a full mirror to operate on — just shape + masked aggregates — combined with checksum-validated identifiers, credential detection, a deterministic routing guard, and a hard no-network / no-LLM guarantee. That's the strictest-isolation end of the spectrum, tuned for confidential financial documents.
Honest trade: obsify optimizes isolation of the values over utility on the data. If you need referentially-intact analytics on a clean copy (cloakbox), reversible round-tripping (redact-mcp), or a multi-language hosted service (cms-ai), those are the better fit — and pair well with obsify rather than competing with it.
Contributing
PRs welcome — see CONTRIBUTING.md for setup, the merge bar, and the
non-negotiable invariants (no LLM calls in the library, no runtime network, no real data,
shape-not-substance). Security issues: SECURITY.md (report privately).
License
MIT — see LICENSE.
obsify MCP 질문
obsify MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add obsify -- uvx obsify를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
obsify MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
원시 데이터가 제 컴퓨터를 떠나나요?
아니요, 서버는 로컬에서 실행되며 결정론적입니다. 모델은 스키마와 합성 트윈을 바탕으로 추론하며, 실제 데이터 내용은 로컬에 유지됩니다.
지원되는 파일 형식은 무엇인가요?
PDF(표 포함), Excel (.xlsx/.xlsm), Word (.docx) 문서를 지원합니다.
민감한 인증 정보는 어떻게 처리하나요?
오탐을 방지하기 위해 엔트로피 휴리스틱 대신 앵커 패턴을 사용하여 클라우드 키, API 토큰, 개인 키 및 DB 연결 문자열을 감지합니다.