emerald-mcp

The MCP server of Emerald: the database under the chat. A .emd file is a real SQLite database on your disk. Keep anything as rows of a table you declare — tasks, meetings, notes, a project's decisions, money — and your assistant asks for the rows it needs instead of re-reading files: typed fields filter exactly, links are followed, and every session sees the same rows. Writes are checked as they land.

claude mcp add emerald -- npx -y emerald-mcp --engine-only

Any MCP client that starts a stdio server runs it the same way: the command npx, the arguments ["-y", "emerald-mcp", "--engine-only"]. Leave the flag off for the ledger's tools too. Every tool takes the absolute path of the .emd it works on. In Claude Code, the plugin brings it with its hooks and a skill: /plugin marketplace add kfireliyahu/emerald-emd, then /plugin install emerald@emerald-emd.

A model works in it

• Your assistant reads and writes the file directly, and where the app draws MCP Apps, shows a table, board or roadmap in the chat.
• Every write is shown first as a dry run. Nothing changes until you say commit.
• It reads what you already keep onto your tables: a spreadsheet (.csv, .xlsx), a .json of rows, or a folder of Markdown notes — a note a row, its frontmatter as columns, its [[links]] as links — read where it is and never changed.
• Shaped tools, never a general query: 28 for any document, 85 with the ledger.
• A document answers in rows, so the model asks for what it needs instead of reading notes end to end.
• One project's session leaves a note in another's inbox, and the next session there starts with it.

Packs

A pack is formats somebody already worked out, with their views, ready to keep in a document. Two come with Emerald:

• The development pack: a project's memory as rows — milestones, units, decisions, open questions, an inbox. A session starts from the rows, not from a summary of a chat.
• The ledger: personal finance from the files you already get — card statements, bank exports, payslips, fund reports. Every total opens to the rows it was summed from. Nothing connects to your bank.

No internet, no login

• The server opens the file it is given, does one job, closes it, and makes no network call of its own.
• The file is yours: sqlite3 and ordinary tools read it; back it up where you like, take it anywhere.

Running it

• emerald-mcp --engine-only — the engine's tools, for any document; a fifth of the definitions to carry.
• emerald-mcp — the engine's tools and the ledger's (a personal-finance pack).
• emerald-mcp watch <document.emd> [--format <name>] — prints a line for each row that changes.
• emerald-mcp init [path/to/document.emd] — run in a repository: creates its document with the development pack (docs/memory.emd unless named; as text inside the repository, so it diffs), writes a marked section of CLAUDE.md with the questions a session starts from and every format's columns, and, where the Claude Code plugin is not installed, its two hooks into .claude/settings.json. A second run changes nothing.

Two more bins are for Claude Code's plugin: emerald-hooks (what its hooks print) and emerald-status-line. They are reached with npx -p emerald-mcp <bin>.

Licensed AGPL-3.0-only; THIRD_PARTY_NOTICES.txt carries the licences of what is bundled.