Maplith Bridge MCP란?
Maplith Bridge은(는) MCP server입니다. MCP를 통해 로컬 데이터 폴더를 읽기 전용으로 공유하며, PostgreSQL 데이터베이스의 내용을 해당 폴더로 추출할 수 있습니다.
프로젝트 README에서 생성된 요약
Maplith Bridge MCP server 정보
Maplith Bridge를 사용하면 개발자가 PostgreSQL 데이터베이스를 읽기 전용 Model Context Protocol 인터페이스를 통해 AI 에이전트에 연결할 수 있습니다. 이 방식은 데이터베이스 테이블을 CSV 또는 JSON과 같은 로컬 데이터 파일 폴더로 추출한 뒤, 이를 MCP 클라이언트와 공유하는 방식으로 작동합니다. 추출기가 데이터베이스 연결을 처리하고 브리지 서버는 결과 파일만 제공하므로, 민감한 데이터베이스 인증 정보가 로컬 머신 외부로 유출되지 않습니다.
사용자는 npm 패키지인 maplith을 설치하여 bridge serve 또는 bridge extract와 같은 명령어로 이를 배포할 수 있습니다. 이 서버는 보안을 위해 설계되었으며, 특정 파일 형식에 대해서만 액세스를 허용하고 인증을 위해 256비트 토큰을 요구합니다. Claude Code, Codex, Claude Desktop을 포함한 다양한 클라이언트와 호환됩니다. 브리지를 사용하면 에이전트가 쓰기 권한이나 인증 정보 노출 위험 없이 list_files 및 read_file과 같은 도구를 통해 구조화된 데이터에 접근할 수 있습니다.
활용 사례
- 1데이터베이스 테이블을 AI 에이전트에 노출PostgreSQL 데이터베이스의 데이터를 로컬 폴더로 가져와 MCP 호환 에이전트가 사용할 수 있도록 설정할 수 있습니다.
- 2로컬 데이터 파일의 안전한 공유보안 토큰을 사용하여 특정 디렉토리의 파일을 MCP를 통해 공유함으로써 무단 액세스를 방지할 수 있습니다.
- 3컨텍스트를 위한 데이터 추출 자동화extractor 명령을 사용하여 데이터베이스 테이블을 CSV 파일로 변환하고 에이전트가 분석할 수 있도록 합니다.
- 4코딩 어시스턴트와 통합Claude Code 또는 Codex 내에 브리지를 설정하여 코딩 에이전트가 시스템 데이터에 직접 접근할 수 있도록 합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Maplith Bridge MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Maplith Bridge MCP 설치
$ claude mcp add agents -- npx -y maplithCursor에 Maplith Bridge MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"agents": {
"command": "npx",
"args": [
"-y",
"maplith"
]
}
}
}VS Code에 Maplith Bridge MCP 설치
.vscode/mcp.json
{
"servers": {
"agents": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"maplith"
]
}
}
}VS Code CLI에 Maplith Bridge MCP 설치
$ code --add-mcp '{"name":"agents","type":"stdio","command":"npx","args":["-y","maplith"]}'Claude Desktop에 Maplith Bridge MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"agents": {
"command": "npx",
"args": [
"-y",
"maplith"
]
}
}
}Codex에 Maplith Bridge MCP 설치
$ codex mcp add agents -- npx -y maplithCodex config.toml에 Maplith Bridge MCP 설치
~/.codex/config.toml
[mcp_servers.agents] command = "npx" args = ["-y", "maplith"]
Gemini CLI에 Maplith Bridge MCP 설치
$ gemini mcp add -s user agents npx -- -y maplithGemini settings.json에 Maplith Bridge MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"agents": {
"command": "npx",
"args": [
"-y",
"maplith"
]
}
}
}자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기Maplith for your agents
Maplith maps how a company's systems fit together, so any AI agent can find the data it needs, by which key, and how far to trust each step. This repository holds the open-source parts that run on your side, next to your agent and your data. One product, three parts:
| Part | What it does | Where |
|---|---|---|
| Plugin for Claude Code and Codex | Maplith in your coding agent with one install: the hosted map over MCP (you sign in; nothing is pasted), Maplith Bridge for a local folder, and a skill that says when and how to use them. | plugins/maplith/ |
| Maplith Bridge | Connect your database to your AI agent, read-only, without giving anyone your password. | this page, from Quick start |
| Maplith Wake | Start your own Claude agent the moment there is work for it, from a small relay in your own account. | wake-relay/ |
All of it is one npm package, maplith,
with one command: maplith setup puts Maplith in your agent, and
maplith bridge is Maplith Bridge.
Set Maplith up in your agent
No account? You create one in the browser window that opens when you sign in, and come straight back. Your agent then builds your first map with you.
One command, with Node.js 24 or newer. It runs your agent's own commands and writes no key anywhere:
npx --yes maplith@1.2.0 setup claude
npx --yes maplith@1.2.0 setup codex
Or by hand. Claude Code:
/plugin marketplace add Maplith/agents
/plugin install maplith@maplith
then run /mcp, choose maplith and Authenticate. OpenAI Codex:
codex plugin marketplace add Maplith/agents
codex plugin add maplith@maplith
codex mcp login maplith
Codex does not pass your environment to a plugin's servers, so to share a
folder with Codex through the Bridge, name it once:
npx --yes maplith@1.2.0 setup codex --dir <folder>.
Everything here is Apache-2.0.
Maplith Bridge (npm: maplith, with the command maplith-bridge as an alias) lives in the
Maplith/agents repository.
Maplith Bridge
Connect your database to your AI agent, read-only, without giving anyone your password.
The Bridge runs in your own network. It shares one folder of data files over MCP (the Model Context Protocol), behind a token you create, and it can fill that folder from PostgreSQL under a database role that can only read.
- Read-only, end to end. The server has no method that writes and accepts no file. The extractor refuses to run under a role that can do more than read.
- Your password stays with you. The database password never leaves the machine the extractor runs on, and the server that faces the network never holds it.
- Small enough to read. Six files of TypeScript: four for the Bridge, and
the
maplithcommand and itssetup. The server runs on Node.js alone; the extractor has one dependency, the PostgreSQL client, pinned.
Any MCP client can use it: Claude Code, Codex, Claude Desktop, your own agent. It works best with Maplith, which reads the folder to map how your systems fit together.
Quick start
You need Node.js 24 or newer.
npx --yes maplith@1.2.0 bridge rotate-token
npx --yes maplith@1.2.0 bridge serve --dir ./exports
The first command writes a random token to maplith-bridge.token, readable
by you only. The second serves the files in ./exports at
http://127.0.0.1:8787/mcp, on this machine only. Point any MCP client at that
address with the header Authorization: Bearer <the token>. With Claude Code:
claude mcp add --transport http bridge http://127.0.0.1:8787/mcp \
--header "Authorization: Bearer $(cat maplith-bridge.token)"
To fill the folder from PostgreSQL, under a read-only role:
PGHOST=db.example.com PGDATABASE=shop PGUSER=bridge_reader \
npx --yes maplith@1.2.0 bridge extract postgres --out ./exports --check
--check verifies the role and writes nothing. Run it again without --check
to write one CSV file per table.
Beside the CSV files of each folder, the extractor writes maplith-schema.json,
which the server shares like any other file: for each table, its file, its
columns with their PostgreSQL attribute numbers and types, its keys and its
estimated row count. It holds names and numbers, never a value, and names the
database only by a digest of its identity (below). A reader can tell
from it that a renamed column is the same column (its attribute number stays)
and that a column dropped and added again is a new one (it gets a new number).
A restore keeps the relation ids and attribute numbers it had, and the next
ADD COLUMN can reuse a number that a later state had given another column.
So the digest is made of the server's system identifier and timeline, when
its statistics were last reset, the database's id and name, and an epoch the
extractor keeps in the folder, and it changes when the extractor sees that the
database's history did not go on from its last run: another server or
database, a new timeline (a point-in-time recovery or a promotion), a reset of
the server's statistics (every start that has to recover resets them: after a
crash, or from a restored snapshot or base backup), a table or column whose
catalog entry was written again before that run (an earlier copy restored,
then changed), or no record of that run in the folder (a first run, a new
install, another folder: its record starts with an epoch of its own, drawn at
random, so it never states the digest another folder stated). One restore goes
unseen: a copy of the data directory taken while the server was stopped and
started again as it was, changed only once its transaction counter had passed
where the original's stood at the extractor's last run (or restored together
with the extractor's folder). The same numbers can then name other columns
under the same digest.
Where the role may not read the system identifier, the timeline or when the
statistics were last reset, the file names no database ("database": null),
and its numbers describe that run only: a restore into a fresh server can give
the same relation ids again, and it renumbers the attribute numbers.
Run any command with --help for every option.
Powered by Maplith Bridge
If you use Maplith Bridge, you are welcome to add this badge to your own site or docs.
HTML:
<a href="https://maplith.com"><img src="https://raw.githubusercontent.com/Maplith/agents/main/assets/powered-by-maplith-bridge.svg" alt="Powered by Maplith Bridge" width="196" height="28"></a>
Markdown:
[](https://maplith.com)
Set it up for real
- RUNBOOK.md: a server install, step by step, for the person who runs it: two system users, the read-only role, TLS, a systemd service.
- INSTALL-WITH-YOUR-AGENT.md: one prompt that has
your own AI agent do the same install, stopping for you at every decision,
password and
sudo.
How it keeps your data safe
| Risk | What the Bridge does |
|---|---|
| Someone on the internet calls it | Every request needs the token: 256 random bits, compared in constant time. Wrong tokens are counted and slowed down. It listens on this machine only unless you give it TLS or name the reverse proxy in front of it, and it refuses plain HTTP on any other address. |
| The token leaks | It opens one folder, read-only, and nothing else. rotate-token replaces it in one command, without a restart. --allow limits who may call. |
| Something harmful is sent in | Nothing is written, uploaded or run. A request is at most 64 KB of JSON and is never evaluated. |
| A request reaches outside the folder | Not through .., a symbolic link or a hidden file. Only CSV, TSV, JSON, JSONL, Markdown and text files are served. |
| Your database password | It stays on the extractor's machine, is never printed or written, and is sent only to the database: over verified TLS by default when the database is on another machine. |
| A tampered package | Releases are built in public CI with provenance, and carry a checksum and a build attestation. The published package runs no install script. |
| A file tries to instruct an agent | The server tells every client that file contents are data, not instructions. |
THREAT-MODEL.md names the tests behind every row.
Verify a release
Every release on GitHub carries the tarball, its SHA-256 checksum and a build
attestation. The same tarball is published to npm with provenance, so npm's
digest of it must match the file from GitHub: the two sha512- lines below
are equal.
sha256sum -c maplith-1.2.0.tgz.sha256
echo "sha512-$(openssl dgst -sha512 -binary maplith-1.2.0.tgz | openssl base64 -A)"
npm view maplith@1.2.0 dist.integrity
gh attestation verify maplith-1.2.0.tgz --repo Maplith/agents \
--bundle maplith-1.2.0.tgz.sigstore.json
After installing from npm, npm audit signatures checks the registry
signature and the provenance.
Use it from any MCP client
The Bridge speaks MCP 2025-06-18 (and 2025-03-26, 2024-11-05) over Streamable
HTTP: JSON-RPC 2.0 requests by POST to /mcp. It offers:
- resources:
resources/list(100 per page, with a cursor) andresources/read; - two read-only tools on the same code path:
list_filesandread_file.
Each top-level folder is one system: exports://shop/orders.csv is the file
orders.csv of the system shop. A file is listed only when it fits in one
reply of at most 8 MB. GET /healthz answers 204 for a health check.
File contents come from your systems. Tell your agent to treat them as data,
never as instructions; the Bridge says the same in its instructions.
Use it from an agent on this machine
An agent that starts its MCP servers as local commands, such as Claude Code, can start the Bridge itself:
npx -y maplith@1.2.0 bridge stdio --dir ./exports
stdio serves the folder to that one agent over its stdin and stdout: the
same server as serve, on 127.0.0.1 only, behind a token that lives only
in its process. There is no token file and nothing to type. The folder comes
from --dir or EXPORT_DIR; without one it serves an empty folder and says
how to name one. The Maplith plugin starts it this way: in Claude Code with
the folder from MAPLITH_BRIDGE_DIR, in Codex with the folder setup codex --dir names. The older command maplith-bridge still works, as
maplith bridge. To share a folder with Maplith or with
an agent on another machine, use serve.
For MCP directories
A directory of MCP servers, such as Glama,
builds this repository in a sandbox and inspects the server over stdio, with
no folder and no token to give it. glama-stdio.ts is the entry for that,
and only for that:
- it creates an empty folder of its own, so there is nothing to share;
- it draws a random token that lives only in its memory: never in a file, an argument, the environment or a log;
- it starts the Bridge's own server on
127.0.0.1, on a free port, serving that folder behind that token; - it relays MCP between stdin and stdout and that server, one JSON-RPC message per line, and logs to stderr only;
- when stdin ends, or on SIGTERM, it stops the server and removes the folder.
A directory sees the Bridge as it is: its initialize reply and
instructions, the tools list_files and read_file, and an empty list of
files. The entry takes no argument and cannot share a folder: serve does
that. It is in this repository, not in the npm package.
With Node.js 24 or newer, from a checkout:
npm ci --ignore-scripts
node glama-stdio.ts
A directory that speaks HTTP to its sandbox puts
mcp-proxy in front of it:
mcp-proxy -- node glama-stdio.ts. On Glama, the server's settings are:
| Setting | Value |
|---|---|
| Node.js version | 24 |
| Build steps | ["npm ci --ignore-scripts"] |
| CMD | ["mcp-proxy", "--", "node", "glama-stdio.ts"] |
| Environment variables | none |
Limits
- PostgreSQL is the one database the extractor reads. Any other system can fill the folder with its own export files.
- The server reads a TLS certificate when it starts: restart it after a renewal.
- Behind two proxies in a row, name both with
--behind-proxy.
Versioning
The Bridge follows semantic versioning. Every change is in CHANGELOG.md.
Contributing, security, licence
- CONTRIBUTING.md: how to propose a change (with a DCO sign-off).
- SECURITY.md: report a vulnerability privately, to security@maplith.com or through GitHub.
- Apache License 2.0 (LICENSE). "Maplith" and the Maplith logo are trademarks of Maplith (TRADEMARK.md).
Maplith Bridge MCP 질문
Maplith Bridge MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add agents -- npx -y maplith를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Maplith Bridge MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
데이터 액세스가 안전한가요?
The Bridge는 엔드 투 엔드 읽기 전용 방식으로 작동하며, 요청 시 256비트 랜덤 토큰이 필요합니다. 또한 데이터베이스 비밀번호가 로컬 머신을 절대 벗어나지 않도록 보장합니다.
지원되는 파일 형식은 무엇인가요?
CSV, TSV, JSON, JSONL, Markdown 및 text 파일을 지원합니다.