Halfnine MCP server
Commit Nov 1, 2026Allows AI agents to describe, query, and perform approved changes on PostgreSQL databases through a controlled interface.
Also known as notinferred/halfnine
- Stars
- 15
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Nov 1, 2026
- License
- —
What is Halfnine MCP?
Halfnine allows AI agents to describe, query, and perform approved changes on PostgreSQL databases through a controlled interface.
Summary generated from the project's README
About Halfnine MCP server
Managing PostgreSQL databases through AI agents is possible with Halfnine, a tool designed for macOS and Windows users. It provides a controlled interface that allows clients like Claude Desktop, Cursor, VS Code, and Claude Code to describe, query, and modify database structures. Users can configure specific permission levels for each connection, ranging from read-only access to full control, ensuring that agents only perform approved changes.
Developers can integrate this server into their local workflows using stdio transport or by adding a specific extension file for Claude Desktop. The system includes built-in support for Docker environments, allowing agents to create, copy, or delete PostgreSQL containers using engines like Docker Desktop, OrbStack, Colima, or Rancher Desktop. To prevent accidental data loss, the software automatically creates backups before an agent drops or empties a table, providing an undo option for these actions.
What you can do with it
- 1Controlled database modificationsAn AI agent can propose SQL changes that appear as staged rows or SQL for your manual approval before execution.
- 2Automated Docker container managementYou can instruct an AI to spin up new PostgreSQL 14 through 18 instances directly within your Docker environment.
- 3Safe data experimentationAn agent can create its own isolated database environment to perform risky work without affecting your main connections.
- 4Accidental deletion protectionThe system safeguards your data by performing automatic backups whenever an agent attempts to drop or empty a table.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenotinferred/halfnine is public and reachablegithub.com/notinferred/halfnine ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-01github.com/notinferred/halfnine ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubHalfnine
A small, calm PostgreSQL client for macOS and Windows, light enough to leave open all day.
It is early: ROADMAP.md says where things stand.
Install
Download the installer from Releases. The builds aren't signed yet, so each system asks once before opening them:
- macOS (Apple silicon, macOS 13 or later): open the
.dmgand drag Halfnine to Applications. Open it once, then choose System Settings › Privacy & Security › Open Anyway. Or runxattr -dr com.apple.quarantine /Applications/Halfnine.app. - Windows (x64): run the
-setup.exe. At the SmartScreen warning choose More info › Run anyway. It installs for the current user, without administrator rights.
When a connection saves its password, macOS asks once before Halfnine first reads it, and again after each update until the app is signed. Choose Always Allow.
Docker databases and backups
Turn on Docker databases in Settings, or at the first launch, and the Postgres containers on this computer show under Docker on the connections screen. Double-click one to connect; Halfnine reads its user and password from the container. The Docker page makes new ones (PostgreSQL 14 to 18, optionally from a dump or an SQL file), copies, starts, stops and deletes them. It works with Docker Desktop, OrbStack, Colima and Rancher Desktop.
With backups on, as they are unless you turn them off in Settings, dropping or emptying a table, dropping a column, or deleting a Docker database backs it up first and acts at once, with Undo at the foot of the window. Backups stay on the Docker page until you delete them. A table bigger than the limit in Settings, or one Halfnine can't back up, asks for its name instead.
Use with AI agents
Halfnine is also an MCP server, so Claude Code, Codex, Cursor, VS Code and Claude Desktop can use your connections through it. Open Agents, at the foot of the sidebar or the connections screen, choose Connect next to your tool, and Halfnine shows what it will change before it adds itself. Or add it by hand; on macOS:
claude mcp add --scope user --transport stdio halfnine -- /Applications/Halfnine.app/Contents/MacOS/halfnine mcp
codex mcp add halfnine -- /Applications/Halfnine.app/Contents/MacOS/halfnine mcp
For Claude Desktop, install Halfnine first, then open the .mcpb file from the same release to add it as an extension. It is also listed in the official MCP Registry as io.github.notinferred/halfnine.
Each connection sets what agents may do there, under Agents in its settings: Off, Read, Read with approved writes, or Full. Red-labelled connections start at Off and every other at Read. At Read with approved writes, an agent's change opens in Halfnine as staged rows or SQL and waits for your answer. Everything agents do is listed on the Agents page, where one switch pauses them all. What an agent reads goes to its AI provider.
With Docker databases on, an agent can make its own databases, or copy one before risky work. Those start at Full and are marked with the agent's name, and it gets their URL for programs it runs. It deletes one made for it without asking; deleting any other asks you. While backups are on, what an agent drops or empties is backed up first, and run_sql won't drop tables, schemas or databases.
Develop
You need Node 24 or later, pnpm (the version in package.json is fetched automatically), Rust through rustup (rust-toolchain.toml picks the version), and on macOS the Xcode Command Line Tools. With Homebrew, brew install rustup, then put /opt/homebrew/opt/rustup/bin on your PATH; Homebrew leaves it off.
| Command | What it does |
|---|---|
pnpm install |
Installs the UI's dependencies |
pnpm dev |
Opens the app, reloading the UI as you edit. The first run compiles the Rust side and takes a few minutes |
pnpm check / pnpm format |
Lints and checks formatting with Biome / applies its fixes |
pnpm typecheck |
Checks the UI's types |
cargo fmt --all |
Formats the Rust crates |
cargo clippy --workspace --all-targets -- -D warnings |
Lints the Rust crates |
pnpm icons |
Renders every app icon size from assets/brand/app-icon.svg |
pnpm tauri build |
Builds the installer for the machine it runs on |
git tag v0.2.0 && git push origin v0.2.0 |
Builds the macOS and Windows installers and the Claude Desktop extension in GitHub Actions into a draft release, to check and publish. Publishing it lists that version in the MCP Registry |
cargo test --workspace |
Runs the Rust tests. The Postgres tests skip themselves unless HN_TEST_DATABASE_URL names a database loaded with crates/pg/tests/fixture.sql, and the Docker tests unless HN_TEST_DOCKER=1 and a Docker engine with postgres:18 pulled is running. They label what they make, and CI removes anything they leave |
To check the app or run the Postgres tests on a Mac without a database, start a throwaway one in Docker. It deletes itself when stopped:
docker run -d --rm --name halfnine-check -e POSTGRES_PASSWORD=check -p 127.0.0.1:55432:5432 postgres:18
docker exec -i halfnine-check psql -U postgres -q < crates/pg/tests/fixture.sql
# connect the app to postgres://postgres:check@localhost:55432/postgres
# or: HN_TEST_DATABASE_URL=postgres://postgres:check@localhost:55432/postgres cargo test --workspace
docker stop halfnine-check
Layout
apps/desktop: the UI, in React and Vite. Design tokens are insrc/ui/tokens.css.crates/desktop: the Tauri app that hosts the UI, with its window, permissions and icons.crates/core,crates/pgandcrates/docker: the types every crate shares, the Postgres adapter, and the Docker engine adapter.docs/: architecture, decisions and brand.
License
Halfnine is source-available under the PolyForm Shield License 1.0.0. You may use it for any purpose, at work included, and change it, but not to sell it or to provide a product that competes with it. Copyright 2026 notInferred.
Halfnine MCP questions
How can I use Halfnine with AI agents like Claude Desktop or Cursor?
You can connect via the Agents menu in the app or add it manually using the provided shell commands for Claude Code or Codex, or by installing the .mcpb extension for Claude Desktop.
Can I control what an AI agent is allowed to do with my database?
Yes, each connection has specific permission settings: Off, Read, Read with approved writes, or Full.
Does Halfnine support Docker databases?
Yes, it can detect, connect to, and manage PostgreSQL containers from Docker Desktop, OrbStack, Colima, and Rancher Desktop.
Is there a way to prevent accidental data loss when an agent runs commands?
Yes, Halfnine includes a backup feature that triggers before dropping or emptying tables, and the run_sql command is restricted from dropping tables, schemas, or databases.