gnucash-mcp

gnucash-mcp

Software akuntansi gratis dan sumber terbuka yang bekerja dengan LLM.

Bicaralah dengan buku GnuCash Anda melalui Claude (atau asisten AI mana pun yang mendukung MCP). Tanyakan "bagaimana kinerja saya bulan ini," diktekan transaksi Anda dengan lantang, serahkan buku kepada AI untuk terus dipelihara sementara Anda fokus menjalani hidup atau bisnis Anda.

Server berjalan di mesin Anda dan bekerja pada file GnuCash lokal Anda; file dan log auditnya tidak pernah meninggalkannya. Asisten AI Anda melihat apa yang dikembalikan oleh panggilan alatnya (saldo, penerima pembayaran, faktur), sama seperti yang Anda lihat di layar.

Melakukan upgrade dari 1.4? Baca panduan upgrade sebelum penulisan pertama Anda dengan 1.5.

Instal dalam satu klik: di Claude Desktop, unduh bundel .mcpb dari rilis terbaru, klik dua kali, dan Anda sudah berjalan — tanpa terminal, tanpa file konfigurasi. Setiap klien MCP lainnya — ChatGPT/Codex, Gemini, Antigravity, dan lainnya — terhubung dengan beberapa baris pengaturan. Apa pun caranya, langganan AI yang sudah Anda bayar menjadi pembukuan yang tidak pernah mengirim tagihan.

Tiga buku contoh realistis memungkinkan Anda mencobanya sebelum menggunakan data apa pun: tahun penuh aktivitas, mata uang campuran, pelanggan, faktur, dan anggaran. Bundel Claude Desktop menyertakannya; dari klon, satu perintah membangunnya. Telusuri satu dalam lima menit; jika cocok, arahkan server ke buku Anda sendiri dan selesai.

---

Seperti apa tampilannya?

Inilah yang dilihat asisten AI Anda saat membuka salah satu buku contoh — dasbor keuangan lengkap dalam satu panggilan:

Book: alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-10-08
Last entry: 2026-10-08 (today)
Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  Liabilities (8 total): Credit Card (3), Loans (3)
  Equity (3 total)
  Income (11 total): Investment Income (6)
  Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
Assets: USD 874270.54
  Condo: USD 475000.00
  VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  UWRP 403(b): USD 74778.40
  Savings Account: USD 60000.00
  Cascade Code LLC Checking: USD 41390.64
  ...
Liabilities: USD 389695.79
  Credit cards (2): USD 1319.99
  Loans & other (2): USD 385873.30
  Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  Accounts Receivable: USD 22425.00
  Accounts Receivable EUR: USD 4899.47
Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  Accounts Payable: USD 2502.50
Jobs: 3 active
Frequently used accounts (last 180 days — any account parameter accepts the %guid or the full name; a %guid is fewer tokens and faster to write):
  %528b7d9	Assets:Current Assets:Checking Account [BANK]
  %8799a0a	Liabilities:Credit Card:Chase Sapphire [CREDIT]
  %839fcf8	Expenses:Dining
  ...
Reconciliation:
  6 accounts current
Net worth trajectory:
  12mo ago: USD 345,969
   6mo ago: USD 381,961
   3mo ago: USD 429,392
   1mo ago: USD 443,546
       now: USD 484,575
Monthly net (income - expenses, last 6 months):
  Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  Sep 2026: +25,894
  Aug 2026: +7,588
  Jul 2026: +10,307
  Jun 2026: +24,092
  May 2026: +9,017
Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
Transactions: 2227
Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
Business: 8 customers, 3 vendors
Budgets: 2
Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX

Itu bukan tangkapan layar — itu adalah tampilan orientasi AI yang sebenarnya. Lintasan kekayaan bersih, landasan pacu, kecepatan anggaran, siapa yang berutang uang kepada Anda, apa yang lewat jatuh tempo, apa yang belum direkonsiliasi. Satu panggilan, dan asisten Anda memiliki gambaran lengkap sebelum Anda bahkan selesai mengucapkan salam.

---

Untuk siapa ini?

• Orang-orang keuangan pribadi yang menyimpan buku mereka di GnuCash dan ingin mendiktekan transaksi, bertanya kepada asisten mereka ke mana uang pergi, mendapatkan bantuan rekonsiliasi, merencanakan anggaran.
• Pemilik usaha kecil yang menjalankan buku mereka di GnuCash dan ingin menerbitkan faktur, melacak piutang, melihat pengeluaran vendor, mengelola arus kas tanpa meninggalkan percakapan.
• Orang-orang yang peduli bahwa data mereka tetap lokal. Tanpa sinkronisasi cloud. Tanpa SaaS. File .gnucash Anda adalah sistem pencatatan; ini hanya memberi AI Anda cara untuk membaca dan menulisnya seperti yang dilakukan GnuCash sendiri.

Anda tidak perlu menjadi pengembang. Anda perlu:

• Komputer (Mac, Windows, atau Linux)
• GnuCash itu sendiri, atau kesediaan untuk menginstalnya (gratis di gnucash.org)
• Asisten AI yang mendukung MCP (Claude Desktop adalah yang paling umum; Claude Code, Continue.dev, dan lainnya juga berfungsi)
• 10 menit untuk menjalankan buku contoh, lalu 10 menit lagi untuk mengarahkannya ke buku Anda sendiri

---

Coba tanpa mengambil risiko apa pun

Repositori menyertakan tiga persona contoh — buku besar sintetis yang dapat Anda ajak bicara tanpa menyentuh data asli Anda. Bundel membawanya sepenuhnya terbangun; dari klon, satu perintah membangunnya. Pilih satu, arahkan server ke sana, dan mulailah mengajukan pertanyaan.

samples/alex-chen-morales.gnucash — Pribadi + pekerja lepas

Kontraktor perangkat lunak independen yang berbasis di Seattle dengan LLC anggota tunggal dan pasangan dengan gaji rumah sakit. Default USD. 111 akun dan lebih dari 2.000 transaksi dari 2025 hingga tanggal pembangunan. Memiliki hipotek, perantara dengan kepemilikan VTSAX/VBTLX/AAPL/MSFT/ETH, Solo 401(k) di samping 403(b) pasangan, delapan pelanggan yang ditagih dalam USD, EUR dan CAD, subkontraktor yang ditagih melalui A/P, pajak B&O Washington, tagihan terjadwal, anggaran — hampir semua yang dapat dilakukan server, semuanya dalam satu buku.

samples/lin-wei.gnucash — Studio perangkat lunak Shenzhen

Pengembang Shenzhen yang menjalankan studio kepemilikan tunggal terdaftar yang membangun perangkat lunak e-commerce lintas batas, dengan pasangan dengan gaji rumah sakit. Default CNY, pada bagan zh_CN asli. 101 akun dan sekitar 3.000 transaksi. Klien teknologi Shenzhen (Tencent, DJI, SF Tech dan lainnya) membayar dalam CNY, klien USD/EUR membayar dalam mata uang asing dengan realisasi keuntungan/kerugian FX pada pergerakan kurs, investasi domestik Tiongkok (宁德时代 dan dua ETF), karyawan paruh waktu, kartu kredit HKD, hipotek, dan jalur pembayaran campuran (akun perusahaan + Alipay + WeChat Pay).

samples/sabine-brenner.gnucash — Pekerja lepas Jerman, bagan SKR03

Desainer lepas yang berbasis di Munich. Default EUR, pada bagan akun SKR03 Jerman — setiap nama akun dalam bahasa Jerman. 125 akun dan sekitar 1.900 transaksi, dengan pengembalian PPN langsung dan mobil perusahaan berdasarkan aturan 1%. Jika fitur mengasumsikan nama akun berbahasa Inggris atau USD, buku Sabine adalah tempat ia rusak.

Ketiga buku itu fiktif. Lihat samples/README.md untuk rincian lengkap apa yang ada di masing-masing.

---

Mulai Cepat

Instal dalam satu klik (Claude Desktop)

Unduh bundel .mcpb dari rilis terbaru dan klik dua kali. Claude Desktop menginstal server — tanpa terminal, tanpa file konfigurasi, tanpa Python. Penginstal menanyakan tiga hal:

• Buku GnuCash Anda — pemilih file. Buku harus dalam format SQLite; jika milik Anda adalah format XML yang lebih lama, lakukan konversi satu kali terlebih dahulu. Pilih beberapa buku untuk beralih di antaranya dalam obrolan.
• Buku demo — satu kotak centang menyajikan tiga buku contoh yang dijelaskan di atas, sehingga Anda dapat menjelajahi uang fiktif sebelum (atau alih-alih) menghubungkan buku Anda sendiri.
• "Apakah Anda menagih klien?" — ya menambahkan paket bisnis (faktur pelanggan, tagihan vendor, pengeluaran karyawan). Segala hal lainnya — anggaran, transaksi terjadwal, pelacakan investasi — selalu aktif.

Itulah seluruh instalasi.

Coba

Tanyakan pada Claude:

• "Ringkas buku ini."
• "Apa yang terjadi dengan kekayaan bersih saya?"
• "Tunjukkan siapa pun yang berutang uang kepada saya."
• "Berapa pengeluaran saya untuk makan di luar bulan lalu?"
• "Tetapkan anggaran belanja bulanan $500."

Respons pertama biasanya dimulai dengan dasbor dari atas. Segala sesuatu setelah itu bersifat percakapan.

Saat Anda siap untuk buku Anda sendiri, lihat Menghubungkan ke buku Anda sendiri di bawah.

Klien AI lainnya, atau menginstal dari sumber

ChatGPT dan Codex, Claude Code, Gemini CLI, Google Antigravity, dan klien MCP lainnya terhubung melalui instalasi dari klon git, begitu juga buku database dan siapa pun yang mengerjakan server: lihat docs/CLIENTS.md.

---

Menghubungkan ke buku Anda sendiri

Konversi satu kali: format file GnuCash

Server hanya membaca bentuk SQLite dari file GnuCash, bukan bentuk XML yang lebih lama. Untuk mengonversi:

1. Buka buku Anda di GnuCash itu sendiri
2. File → Simpan Sebagai
3. Ubah "Format Data" menjadi SQLite3
4. Simpan dengan nama file baru (mis. mybook-sqlite.gnucash)
5. Simpan XML asli sebagai cadangan.

Di Linux (Debian/Ubuntu), SQLite3 mungkin tidak ada di menu tarik-turun "Format Data" sama sekali — GnuCash memerlukan driver backend yang tidak diinstal secara default. Tutup GnuCash, instal, lalu buka kembali dan opsi akan muncul:

sudo apt update && sudo apt install libdbd-sqlite3

Anda hanya melakukan ini sekali. Sejak saat itu, GnuCash dan server MCP keduanya bekerja pada file SQLite yang sama.

GnuCash 3.8 atau lebih baru. Setelah server menulis ke buku, buku tersebut membawa penanda fitur ("Gunakan tanda alami dalam jumlah anggaran") yang diperkenalkan GnuCash 3.8, dan GnuCash 3.0–3.7 menolak untuk membuka buku yang ditandai dengan fitur yang tidak diketahuinya. GnuCash 3.8 dan yang lebih baru menandai buku apa pun dengan anggaran dengan cara yang sama saat membukanya, jadi ini hanya penting jika Anda masih menjalankan 3.x yang lebih lama. Server diuji terhadap GnuCash 5.12.

Arahkan server ke sana

Dengan bundel, pilih buku di pengaturan ekstensi GnuCash di Claude Desktop, lalu mulai ulang Claude Desktop. Dengan instalasi klon, atur GNUCASH_BOOK_PATH ke jalur absolut buku; lihat Menggunakan buku Anda sendiri.

Atau: simpan buku di PostgreSQL atau MySQL

GnuCash juga dapat menyimpan buku di database alih-alih file, dan server juga melayani salah satunya. Arahkan ke string koneksi alih-alih jalur:

{
  "command": "/Users/yourname/.local/bin/gnucash-mcp",
  "args": ["--modules=all"],
  "env": {
    "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
    "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  }
}

Instal driver di samping server — postgres atau mysql (MariaDB menggunakan yang sama). Dari dalam klon Anda (folder gnucash-mcp; lihat menginstal dari sumber):

uv tool install -e ".[postgres]" --reinstall

Untuk MySQL / MariaDB string koneksinya adalah mysql+pymysql://user:password@localhost:3306/gnucash dan ekstranya adalah [mysql]: uv tool install -e ".[mysql]" --reinstall. Bentuk yang lebih pendek yang ditulis GnuCash sendiri, mysql:// dan postgres://, juga berfungsi; server menggunakan driver yang diinstal ekstra.

Instal dari klon, seperti di atas, bukan berdasarkan nama: nama gnucash-mcp di PyPI milik proyek yang berbeda.

Untuk memindahkan buku yang ada: buka di GnuCash, File → Simpan Sebagai, pilih postgres atau mysql, dan isi detail koneksi. (Di Debian/Ubuntu entri tersebut memerlukan sudo apt install libdbd-pgsql or libdbd-mysql, dengan cara yang sama SQLite3 memerlukan libdbd-sqlite3; build macOS dan Windows menyertakan ketiganya.) Simpan file — file tersebut tetap menjadi cadangan yang sangat baik untuk semua hingga saat Anda beralih.

Perlu diketahui sebelum beralih:

• GNUCASH_BOOK_PATH dan GNUCASH_BOOK_URI saling eksklusif — buku adalah file atau database, dan mengatur keduanya adalah kesalahan startup alih-alih lemparan koin tentang buku besar mana tempat penulisan Anda masuk.
• GNUCASH_LOG_DIR menjadi wajib. Log audit dan debug biasanya berada di folder di samping file buku; string koneksi tidak memiliki "di samping".
• Satu buku per server. switch_book cocok dengan nama file, jadi multi-buku tetap menjadi fitur file.
• Server berhenti mengambil cadangan. Ini adalah trade-off yang sebenarnya: jaring pengaman otomatis ada karena dapat mengambil snapshot file, dan tidak dapat mengambil snapshot database Anda. create_backup mengatakannya alih-alih berpura-pura. Atur pg_dump atau mysqldump secara terjadwal sebelum memindahkan buku asli — lihat docs/RESTORE_FROM_BACKUP.md.
• Kata sandi Anda disamarkan di mana pun server menyebutkan buku — di hasil alat, di header dasbor, dan di log audit — dan di setiap pesan kesalahan, baris log, dan kesalahan startup, termasuk yang ditulis driver database. Kata sandi yang diberikan sebagai parameter kueri (?password=…, sslpassword=…) disamarkan dengan cara yang sama.
• Letakkan string koneksi di blok env, bukan di baris perintah. --book-uri berfungsi, tetapi kata sandi di baris perintah terlihat oleh setiap pengguna mesin dalam daftar proses. Di PostgreSQL Anda juga dapat menghilangkan kata sandi dari string sepenuhnya dan membiarkan driver membaca PGPASSWORD atau ~/.pgpass.

Kedua dialek diuji oleh rangkaian pengujian dan CI: PostgreSQL 16 dan MariaDB 11, masing-masing terhadap server nyata.

---

Memilih set modul

--modules=all adalah default yang mudah — setiap alat, 86 di antaranya. Untuk penggunaan sehari-hari Anda mungkin menginginkan lebih sedikit. Pilih peran yang sesuai dengan cara Anda berbicara dengan server; Anda juga dapat memilih modul di balik setiap peran secara individual untuk potongan yang lebih halus.

Peran	Apa yang diberikannya kepada Anda	Alat
core	Primitif buku besar — akun, transaksi, saldo, slot, log audit, cadangan, neraca, rekonsiliasi. Selalu dimuat.	29
bookkeeper	Segala sesuatu kecuali bisnis: laporan, anggaran, transaksi terjadwal, harga, dan lot investasi. Set keuangan pribadi.	30
investor	Pelacakan basis biaya dan manajemen harga saja (subset dari bookkeeper).	13
business	Pelanggan, vendor, dan karyawan; faktur, tagihan, voucher, dan nota kredit; pajak penjualan, syarat pembayaran, pekerjaan, dan laporan vendor.	27

Pilih satu atau lebih, dipisahkan koma:

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=business"]              // invoicing, freelance or small business
"args": ["--modules=bookkeeper,business"]   // everything (same as all)

core tetap ditambahkan. freelancer dan business_complete, nama yang digunakan 1.4, masih diterima dan berarti business. Modul di balik setiap peran (reconciliation, reporting, budgets, scheduling, tax_lots, portfolio, dll.) juga dapat dipilih satu per satu — jalankan uv run gnucash-mcp --help dari repositori untuk menu lengkap.

---

Apa yang bisa Anda minta untuk dilakukan

Tur yang tidak lengkap. Ungkapkan salah satu dari ini secara alami — asisten akan menerjemahkannya.

Memasukkan seluruh laporan

"Ini laporan rekening checking bulan Agustus saya." (lampirkan PDF-nya)

31 baris dilatih terhadap buku Anda: 24 baru, 6 sudah dimasukkan (diklaim), 1 perlu diperiksa — ini perbandingannya. Konfirmasi dan saya akan menyelesaikan bulan ini: dimasukkan, dikategorikan, dan direkonsiliasi dengan saldo penutup dalam satu langkah.

Satu laporan, dua panggilan, buku yang cocok. Uji coba mengklasifikasikan setiap baris dengan bukti sebelum apa pun ditulis, dan commit menolak secara keseluruhan daripada menyelesaikan bulan yang tidak cocok.

Mencatat aktivitas

"Saya menghabiskan $47,50 di Safeway hari ini untuk bahan makanan, dibayar dengan Visa saya."

Tercatat: $47,50 dari Credit Card:Visa ke Expenses:Groceries pada 30 Apr 2026. Deskripsi: "Safeway".

Menyiapkan tagihan berulang

"Atur sewa saya sebagai tagihan berulang. $1.850 pada tanggal 1 setiap bulan dari checking."

Transaksi terjadwal "Monthly Rent" dibuat: $1.850 bulanan, dari Assets:Checking ke Expenses:Rent. Jatuh tempo berikutnya: 1 Mei 2026.

Pelacakan investasi

"Saya membeli $1.000 VTSAX seharga $170,99/lembar di 401(k) saya."

Pembelian VTSAX tercatat: 5,85 lembar seharga $170,99/lembar. Dasar biaya: $1.000,00. Lot dibuat untuk pelacakan keuntungan modal saat Anda akhirnya menjual.

Membuat faktur pelanggan

"Buat pelanggan bernama Acme Corp dan faktur mereka $1.500 untuk konsultasi."

Pelanggan Acme Corp (id 000005) dan faktur 000019 dibuat: 1× Consulting seharga $1.500,00 = $1.500,00. Terbuka. Beri tahu saya saat Anda siap untuk mempostingnya.

Jika Anda membuka faktur yang diposting server di dialog Process Payment GnuCash, atur akun "Post To" ke piutang faktur terlebih dahulu: dialog hanya mencantumkan dokumen yang diposting ke akun yang dipilih.

Faktur mata uang asing

"Faktur Berlin Digital €4.200 untuk retainer Q1, jatuh tempo dalam 30 hari."

Faktur EUR 000020 untuk Berlin Digital GmbH dibuat: 1× Q1 Retainer sebesar EUR 4.200 = EUR 4.200. Net 30. Saat mereka membayar, saya akan membukukan keuntungan/kerugian kurs realisasi ke akun FX Anda secara otomatis.

Mengajukan pertanyaan

"Berapa banyak yang saya keluarkan dengan setiap vendor tahun ini?"

Office Depot: $2.340 (4 tagihan, $0 belum dibayar) CloudHost Inc: $1.200 (2 tagihan, $600 belum dibayar) Legal Associates: $3.500 (1 tagihan, $3.500 belum dibayar) Total ditagih $7.040 / dibayar $2.940 / belum dibayar $4.100.

Rekonsiliasi

"Bantu saya merekonsiliasi checking dengan laporan April."

[Memandu Anda melaluinya: menarik split yang belum direkonsiliasi, meminta Anda untuk mengonfirmasi transaksi yang sudah jelas, menghitung saldo berjalan, menandai yang cocok sebagai direkonsiliasi, meninggalkan yang tidak cocok untuk Anda selidiki.]

---

Privasi dan keamanan

File buku Anda tidak pernah meninggalkan mesin Anda. Server ini adalah proses lokal yang membaca dan menulis file lokal. Asisten AI yang Anda ajak bicara (Claude Desktop, dll.) melihat hasil panggilan alat Anda — konten yang sama yang akan Anda lihat di layar — tetapi file itu sendiri tetap di tempatnya.

Setiap penulisan dicatat. Jejak audit yang dapat dibaca manusia berada di samping file buku Anda di <your-book>.gnucash.mcp/audit/, satu file log per hari. Anda dapat membacanya kapan saja untuk melihat persis apa yang berubah dan kapan. Contoh entri:

2026-04-30 14:32  POST INVOICE  id:000019
    total: 1500.00  date: 2026-04-30
    account: Assets:Accounts Receivable  txn:a1b2c3d4

Cadangan otomatis. Sebelum penulisan pertama setiap sesi (dan lagi saat sesi berjalan lama melewati periode cadangan baru), server memotret buku Anda ke <your-book>.gnucash.mcp/backups/ — jadi jika ada yang salah, Anda dapat memutar kembali ke kondisi yang diketahui baik tanpa mengandalkan Time Machine atau kebiasaan Anda sendiri. Cadangan diverifikasi dengan PRAGMA integrity_check sebelum dinyatakan valid, dan dilewati saat buku tidak berubah sejak snapshot terakhir. Lihat docs/RESTORE_FROM_BACKUP.md untuk prosedur pemutaran kembali.

Membaca stempel waktu: nama file cadangan membawa stempel waktu UTC (aman untuk sistem file dan tidak ambigu di seluruh perjalanan dan DST); log audit dan debug menggunakan file harian berbasis tanggal lokal, cocok dengan cara Anda mencari "apa yang terjadi Selasa." Mendekati tengah malam ini bisa berbeda satu hari — ingat itu saat mencocokkan cadangan dengan log hari itu.

Split yang direkonsiliasi dilindungi. Server menolak untuk menghapus atau memodifikasi split yang direkonsiliasi tanpa penggantian eksplisit, sehingga prompt yang ceroboh tidak dapat membatalkan rekonsiliasi bank terakhir Anda secara diam-diam.

Void ≠ menghapus. Saat Anda memberi tahu AI untuk "void transaksi ini," itu menggunakan void akuntansi GnuCash yang tepat — mempertahankan transaksi untuk jejak audit dengan nilai dinolkan. Penghapusan adalah opsi destruktif; AI akan memberi tahu Anda yang mana yang dilakukannya.

Penafian: Perangkat lunak ini disediakan "sebagaimana adanya" di bawah Lisensi MIT, tanpa jaminan apa pun. Penulis tidak bertanggung jawab atas kehilangan data, korupsi, atau perbedaan keuangan yang timbul dari penggunaannya. Anda sepenuhnya bertanggung jawab untuk memelihara cadangan Anda sendiri dan memverifikasi keakuratan buku Anda.

---

Keterbatasan yang diketahui

• Jangan mengedit di GnuCash desktop dan melalui server secara bersamaan. Server menghormati kunci GnuCash tetapi tidak memegang kunci sendiri (membuka buku untuk satu panggilan pada satu waktu), jadi GnuCash tidak akan memperingatkan Anda bahwa server menggunakan buku.
• Buku dengan "Use Trading Accounts" aktif: transaksi lintas mata uang atau komoditas, termasuk pembelian saham dan dana, ditolak, karena server belum dapat menulis split trading seperti yang dilakukan GnuCash. Masukkan itu di GnuCash desktop; semua dalam satu mata uang berfungsi seperti biasa.
• GnuCash 3.8 atau lebih baru. Buku yang telah ditulis server membawa penanda fitur yang tidak dapat dibuka GnuCash 3.0–3.7.
• Pengeluaran dan pendapatan mata uang asing dinilai pada kurs penutupan setiap bulan di laporan pengeluaran dan pendapatan, bukan pada kas yang membayarnya; cash_flow melaporkan kas.

Daftar lengkap ada di CHANGELOG.md.

---

Membatasi apa yang dapat dilihat AI

Deskripsi setiap alat ada di prompt sistem AI, yang menghabiskan konteks pada setiap pesan. Mempersempit perangkat alat ke apa yang benar-benar Anda gunakan membuat setiap percakapan lebih murah. Lihat memilih set modul di atas untuk empat peran (core, bookkeeper, investor, business).

Anda juga dapat mengatur GNUCASH_MCP_MODULES=core,bookkeeper sebagai variabel lingkungan alih-alih --modules=... di argumen JSON.

---

Apa yang baru di v1.5.0

• Buku dalam database. Arahkan server ke buku yang disimpan GnuCash di PostgreSQL atau MySQL/MariaDB, bukan hanya file SQLite — lihat Atau: simpan buku di PostgreSQL atau MySQL. Dukungan PostgreSQL disumbangkan oleh @vchatela.
• Semuanya disimpan dengan cara GnuCash desktop menyimpannya. Transaksi terjadwal berjalan di Since Last Run desktop, anggaran, faktur, kredit note, void, dan harga terbaca sama di keduanya, dan total faktur cocok dengan GnuCash sendiri hingga sen. Meningkatkan dari 1.4? Baca panduan peningkatan terlebih dahulu.
• Pembayaran di muka. Catat kelebihan pembayaran pelanggan atau vendor sebagai uang yang dipegang untuk mereka, selesaikan faktur nanti darinya, dan batalkan posting faktur yang dibayar tanpa kehilangan pembayaran.
• Tautan Num dan dokumen di setiap alat transaksi, dengan nomor digunakan sebagai pemeriksaan duplikat.
• Peta bagan akun Anda di dasbor, sehingga asisten tahu di mana setiap akun berada sebelum bertanya.
• Buku sampel dibangun dari sumber, masing-masing diperiksa terhadap praktik pajak negaranya sendiri (AS/Washington, Jerman, Tiongkok) dan terkini hingga hari dibangun.

Rilis sebelumnya ada di CHANGELOG.md.

---

Pemecahan masalah

Tidak ada ikon 🔨 palu, atau "tool not found"

• Keluar dari Claude Desktop sepenuhnya, lalu buka kembali. (Menutup jendela tidak cukup — Anda harus keluar dari aplikasi.)
• Verifikasi bahwa jalur di konfigurasi Anda absolut dan benar.
• Periksa JSON untuk koma tambahan — itu merusak konfigurasi secara diam-diam.

"Book not found"

• Gunakan jalur absolut, bukan ~ atau jalur relatif.
• Mac/Linux: /Users/yourname/Documents/book.gnucash
• Windows: C:\\Users\\yourname\\Documents\\book.gnucash (garis miring ganda — persyaratan JSON)

"Cannot open book" / kesalahan piecash

• Konfirmasi bahwa buku Anda dalam format SQLite, bukan XML.
• Pastikan GnuCash tidak terbuka dengan buku yang sama — kunci file. Server menghormati kunci GnuCash tetapi sengaja tidak mengambil kunci sendiri (memegang buku untuk satu panggilan pada satu waktu), jadi GnuCash akan membuka buku yang digunakan server tanpa peringatan. Jangan mengedit di keduanya sekaligus.
• Coba buka buku di GnuCash itu sendiri untuk memverifikasi tidak rusak.

Docker: "both GNUCASH_BOOK_PATH and GNUCASH_BOOK_URI are set"

Image dikirim dengan GNUCASH_BOOK_PATH menunjuk ke buku demo yang dibundel. Untuk melayani buku database darinya, bersihkan default itu di baris perintah (-e GNUCASH_BOOK_PATH=) di samping GNUCASH_BOOK_URI Anda; untuk melayani file yang dipasang, atur GNUCASH_BOOK_PATH ke jalur yang dipasang dan jalankan kontainer sebagai pengguna yang memiliki file (--user "$(id -u):$(id -g)").

"Account not found"

• Gunakan jalur akun lengkap: Expenses:Groceries, bukan hanya Groceries.
• Atau minta asisten untuk mencantumkan akun: "Daftarkan akun saya."

Beberapa proses server setelah restart klien

Claude Desktop (dan beberapa klien MCP lainnya) mungkin sempat memunculkan dua atau tiga salinan server saat diluncurkan ulang. Ini adalah perilaku klien, bukan bug server, dan sebagian besar tidak berbahaya: server membuka buku Anda per-permintaan dan melepaskan kunci file di antara panggilan, jadi proses yang tumpang tindih hanya bersaing sesaat. Jika Anda melihat kesalahan Lock on the file yang persisten setelah restart klien, keluar dari klien sepenuhnya, konfirmasi dengan pgrep -fl gnucash-mcp bahwa tidak ada yang tersisa, dan luncurkan ulang.

Sesuatu salah

• Buka log audit di <your-book>.gnucash.mcp/audit/ — setiap penulisan sejak server pertama kali berjalan ada di sana dengan detail sebelum/sesudah.
• Jika Anda perlu memutar kembali, docs/RESTORE_FROM_BACKUP.md memandu Anda melaluinya.

---

Dukung proyek

Jika gnucash-mcp berguna bagi Anda, pertimbangkan membelikan saya kopi. Ini membantu menjaga pengembangan tetap berjalan.

---

Untuk pengembang

Panduan kontributor dan catatan desain ada di CLAUDE.md. Orientasi cepat:

uv sync --extra dev
uv run pytest                       # 3,300+ tests as of v1.5.0, parallel by default
uv run ruff check src/ tests/
uv run black --check src/ tests/

Perintah gnucash-mcp yang terinstal melacak clone Anda secara langsung: ia melayani cabang apa pun yang sedang diperiksa, jadi mengganti cabang mengganti kode yang dilayani pada restart berikutnya — berguna untuk pengujian, layak diingat saat Anda lupa sedang di tengah cabang. Untuk menjalankan checkout BERBEDA (worktree kedua) tanpa menyentuh instalasi, uv run --directory PATH gnucash-mcp masih menjalankan direktori apa pun yang Anda arahkan.

Server dibangun di atas piecash (antarmuka Python ke buku SQLite GnuCash) dan MCP Python SDK. Sekitar 18.000 baris sumber Python, 20.000 baris tes, dimodulasi sehingga modul yang dinonaktifkan tidak memakan biaya saat runtime.

Lisensi

MIT.

Ucapan terima kasih

• GnuCash — perangkat lunak akuntansi gratis dan sumber terbuka yang dibuat percakapan oleh server ini.
• piecash — antarmuka Python ke buku SQLite GnuCash.
• MCP Python SDK — implementasi Model Context Protocol.