gnucash-mcp

gnucash-mcp

ซอฟต์แวร์บัญชีโอเพนซอร์สฟรีที่ทำงานร่วมกับ LLM

พูดคุยกับสมุดบัญชี GnuCash ของคุณผ่าน Claude (หรือผู้ช่วย AI ใดๆ ที่รองรับ MCP) ถามว่า "เดือนนี้ฉันเป็นอย่างไรบ้าง" พูดคำสั่ง รายการธุรกรรมของคุณออกมาดังๆ ส่งสมุดบัญชีให้ AI ดูแล ในขณะที่คุณโฟกัสกับการใช้ชีวิตหรือธุรกิจของคุณ

เซิร์ฟเวอร์ทำงานบนเครื่องของคุณและทำงานกับไฟล์ GnuCash ในเครื่องของคุณ ไฟล์และบันทึกการตรวจสอบจะไม่ถูกส่งออกไป ผู้ช่วย AI ของคุณจะเห็นสิ่งที่เครื่องมือคืนกลับมา (ยอดคงเหลือ ผู้รับเงิน ใบแจ้งหนี้) เหมือนกับที่คุณเห็นบนหน้าจอ

อัปเกรดจาก 1.4 หรือไม่? อ่าน คู่มือการอัปเกรด ก่อนการเขียนครั้งแรกด้วย 1.5

ติดตั้งในคลิกเดียว: บน Claude Desktop ดาวน์โหลด ชุด .mcpb จาก รุ่นล่าสุด ดับเบิลคลิก แล้วคุณก็พร้อมใช้งาน — ไม่ต้องใช้เทอร์มินัล ไม่ต้องใช้ไฟล์คอนฟิก ไคลเอนต์ MCP อื่นๆ ทุกตัว — ChatGPT/Codex, Gemini, Antigravity และอื่นๆ — เชื่อมต่อด้วย การตั้งค่าไม่กี่บรรทัด ไม่ว่าจะด้วยวิธีใด การสมัครสมาชิก AI ที่คุณจ่ายอยู่แล้วจะกลายเป็นนักบัญชีที่ไม่เคยส่งบิล

สมุดตัวอย่างที่สมจริงสามเล่มให้คุณลองก่อนที่จะผูกมัด อะไร: กิจกรรมตลอดทั้งปี สกุลเงินผสม ลูกค้า ใบแจ้งหนี้ และงบประมาณ ชุด Claude Desktop รวมไว้ให้แล้ว จากการโคลน หนึ่งคำสั่งสร้างมันขึ้นมา ลองดูหนึ่งเล่มในห้านาที ถ้าใช้ได้ ชี้เซิร์ฟเวอร์ไปที่ สมุดของคุณเองแล้วเสร็จ

---

มันมีลักษณะอย่างไร?

นี่คือสิ่งที่ผู้ช่วย AI ของคุณเห็นเมื่อเปิดสมุดตัวอย่าง เล่มหนึ่ง — แดชบอร์ดการเงินที่สมบูรณ์ในการเรียกครั้งเดียว:

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

นั่นไม่ใช่ภาพหน้าจอ — นั่นคือมุมมองปฐมนิเทศที่แท้จริงของ AI เส้นทางมูลค่าสุทธิ ระยะเวลาการดำเนินงาน จังหวะงบประมาณ ใครเป็นหนี้คุณ อะไรค้างชำระ อะไรยังไม่ถูกกระทบยอด หนึ่งการเรียก และผู้ช่วยของคุณมีภาพรวมทั้งหมดก่อนที่คุณจะพูดจบประโยคทักทาย

---

สิ่งนี้เหมาะกับใคร?

• คนที่จัดการการเงินส่วนตัว ที่เก็บสมุดบัญชีใน GnuCash และต้องการสั่งรายการธุรกรรม ถามผู้ช่วยว่าเงินไปไหน ขอความช่วยเหลือในการกระทบยอด วางแผนงบประมาณ
• เจ้าของธุรกิจขนาดเล็ก ที่ทำบัญชีใน GnuCash และ ต้องการออกใบแจ้งหนี้ ติดตามลูกหนี้ ดูค่าใช้จ่ายจากซัพพลายเออร์ จัดการกระแสเงินสดโดยไม่ต้องออกจากการสนทนา
• คนที่ใส่ใจว่าข้อมูลของตนอยู่ในเครื่อง ไม่มีการซิงก์คลาวด์ ไม่มี SaaS ไฟล์ .gnucash ของคุณคือระบบบันทึกหลัก สิ่งนี้เพียงให้ AI ของคุณมีวิธีอ่านและเขียนเหมือนที่ GnuCash ทำ

คุณไม่จำเป็นต้องเป็นนักพัฒนา คุณต้องมี:

• คอมพิวเตอร์ (Mac, Windows หรือ Linux)
• GnuCash เอง หรือยินดีติดตั้ง (ฟรีที่ gnucash.org)
• ผู้ช่วย AI ที่รองรับ MCP (Claude Desktop เป็นที่นิยมที่สุด Claude Code, Continue.dev และอื่นๆ ก็ใช้ได้)
• 10 นาทีเพื่อให้สมุดตัวอย่างทำงาน จากนั้นอีก 10 นาที เพื่อชี้ไปที่สมุดของคุณเอง

---

ลองโดยไม่เสี่ยงอะไร

ที่เก็บโค้ดมาพร้อมกับสามบุคลิกตัวอย่าง — สมุดบัญชีสังเคราะห์ที่คุณ สามารถพูดคุยได้โดยไม่แตะข้อมูลจริงของคุณ ชุดรวมมาพร้อมกับ ที่สร้างเสร็จแล้ว จากการโคลน หนึ่งคำสั่งสร้างมันขึ้นมา เลือกหนึ่งเล่ม ชี้เซิร์ฟเวอร์ไปที่มัน แล้วเริ่มถามคำถาม

samples/alex-chen-morales.gnucash — บุคคล + ฟรีแลนซ์

ผู้รับเหมาซอฟต์แวร์อิสระในซีแอตเทิลที่มี LLC สมาชิกคนเดียวและคู่สมรสที่ทำงานเงินเดือนโรงพยาบาล ค่าเริ่มต้นเป็น USD 111 บัญชีและธุรกรรมมากกว่า 2,000 รายการตั้งแต่ปี 2025 ถึงวันที่สร้าง มีสินเชื่อบ้าน โบรกเกอร์ที่มีการถือครอง VTSAX/VBTLX/AAPL/MSFT/ETH Solo 401(k) ข้าง 403(b) ของคู่สมรส ลูกค้าแปดราย ที่ออกใบแจ้งหนี้เป็น USD, EUR และ CAD ผู้รับเหมาช่วงที่เรียกเก็บผ่าน A/P ภาษี B&O ของวอชิงตัน บิลตามกำหนด งบประมาณ — เกือบทุกอย่างที่เซิร์ฟเวอร์ทำได้ ทั้งหมดในสมุดเล่มเดียว

samples/lin-wei.gnucash — สตูดิโอซอฟต์แวร์เซินเจิ้น

นักพัฒนาในเซินเจิ้นที่ดำเนินสตูดิโอเจ้าของคนเดียวที่จดทะเบียน ซึ่งสร้างซอฟต์แวร์อีคอมเมิร์ซข้ามพรมแดน โดยมีคู่สมรสที่ ทำงานเงินเดือนโรงพยาบาล ค่าเริ่มต้นเป็น CNY บนผังบัญชี zh_CN ดั้งเดิม 101 บัญชีและธุรกรรมประมาณ 3,000 รายการ ลูกค้าเทคในเซินเจิ้น (Tencent, DJI, SF Tech และอื่นๆ) จ่ายเป็น CNY ลูกค้า USD/EUR จ่ายเป็นสกุลเงินต่างประเทศพร้อม กำไร/ขาดทุนจากอัตราแลกเปลี่ยนที่เกิดขึ้นจริง การลงทุนในประเทศจีน (宁德时代 และ ETF สองตัว) พนักงานพาร์ทไทม์ บัตรเครดิต HKD สินเชื่อบ้าน และช่องทางการชำระเงินแบบผสม (บัญชีบริษัท + Alipay + WeChat Pay)

samples/sabine-brenner.gnucash — ฟรีแลนซ์ชาวเยอรมัน ผังบัญชี SKR03

นักออกแบบฟรีแลนซ์ในมิวนิก ค่าเริ่มต้นเป็น EUR บน ผังบัญชี SKR03 ของเยอรมัน — ทุกชื่อบัญชีเป็นภาษาเยอรมัน 125 บัญชีและธุรกรรมประมาณ 1,900 รายการ พร้อมการคืนภาษีมูลค่าเพิ่ม แบบสดและรถบริษัทภายใต้กฎ 1% หากฟีเจอร์ใดสมมติชื่อบัญชี ภาษาอังกฤษหรือ USD สมุดของ Sabine คือจุดที่มันพัง

สมุดทั้งสามเล่มเป็นเรื่องสมมติ ดู samples/README.md สำหรับรายละเอียดทั้งหมด ของสิ่งที่อยู่ในแต่ละเล่ม

---

เริ่มต้นอย่างรวดเร็ว

ติดตั้งในคลิกเดียว (Claude Desktop)

ดาวน์โหลด ชุด .mcpb จาก รุ่นล่าสุด และดับเบิลคลิก Claude Desktop ติดตั้งเซิร์ฟเวอร์ — ไม่ต้องใช้ เทอร์มินัล ไม่ต้องใช้ไฟล์คอนฟิก ไม่ต้องใช้ Python ตัวติดตั้งถามสามสิ่ง:

• สมุด GnuCash ของคุณ — ตัวเลือกไฟล์ สมุดต้องอยู่ใน รูปแบบ SQLite หากของคุณเป็นรูปแบบ XML ที่เก่ากว่า ให้ทำ การแปลงครั้งเดียว ก่อน เลือกหลายสมุดเพื่อสลับระหว่างกันในแชท
• สมุดตัวอย่าง — ช่องทำเครื่องหมายหนึ่งช่องให้บริการสมุดตัวอย่าง สามเล่มที่อธิบายข้างต้น เพื่อให้คุณสำรวจด้วยเงินสมมติก่อน (หรือแทน) การเชื่อมต่อของคุณเอง
• "คุณออกใบแจ้งหนี้ให้ลูกค้าหรือไม่?" — ใช่เพิ่มชุดธุรกิจ (ใบแจ้งหนี้ลูกค้า บิลซัพพลายเออร์ ค่าใช้จ่ายพนักงาน) ทุกอย่างอื่น — งบประมาณ ธุรกรรมตามกำหนด การติดตามการลงทุน — เปิดใช้งานเสมอ

นั่นคือการติดตั้งทั้งหมด

ลองใช้

ถาม Claude:

• "สรุปสมุดบัญชี"
• "มูลค่าสุทธิของฉันเป็นอย่างไรบ้าง"
• "แสดงคนที่ค้างเงินฉัน"
• "เดือนที่แล้วฉันใช้จ่ายค่าอาหารเท่าไหร่"
• "ตั้งงบประมาณซื้อของชำ 500 ดอลลาร์ต่อเดือน"

คำตอบแรกมักเริ่มต้นด้วยแดชบอร์ดจาก ด้านบน ทุกอย่างหลังจากนั้นเป็นการสนทนา

เมื่อคุณพร้อมสำหรับสมุดของคุณเอง ดู การเชื่อมต่อกับสมุดของคุณเอง ด้านล่าง

ไคลเอนต์ AI อื่นๆ หรือติดตั้งจากซอร์ส

ChatGPT และ Codex, Claude Code, Gemini CLI, Google Antigravity และไคลเอนต์ MCP อื่นๆ เชื่อมต่อผ่านการติดตั้งจากการโคลน git เช่นเดียวกับสมุดฐานข้อมูลและใครก็ตามที่ทำงานบนเซิร์ฟเวอร์: ดู docs/CLIENTS.md

---

การเชื่อมต่อกับสมุดของคุณเอง

การแปลงครั้งเดียว: รูปแบบไฟล์ GnuCash

เซิร์ฟเวอร์อ่านเฉพาะรูปแบบ SQLite ของไฟล์ GnuCash ไม่ใช่ รูปแบบ XML ที่เก่ากว่า ในการแปลง:

1. เปิดสมุดของคุณใน GnuCash เอง
2. ไฟล์ → บันทึกเป็น
3. เปลี่ยน "รูปแบบข้อมูล" เป็น SQLite3
4. บันทึกด้วยชื่อไฟล์ใหม่ (เช่น mybook-sqlite.gnucash)
5. เก็บไฟล์ XML ต้นฉบับไว้เป็นข้อมูลสำรอง

บน Linux (Debian/Ubuntu), SQLite3 อาจหายไปจากเมนู "รูปแบบข้อมูล" ทั้งหมด — GnuCash ต้องใช้ไดรเวอร์แบ็กเอนด์ ที่ไม่ได้ติดตั้งตามค่าเริ่มต้น ปิด GnuCash ติดตั้งมัน แล้ว เปิดใหม่และตัวเลือกจะปรากฏ:

sudo apt update && sudo apt install libdbd-sqlite3

คุณทำเพียงครั้งเดียว จากนั้น GnuCash และเซิร์ฟเวอร์ MCP ทำงานกับไฟล์ SQLite เดียวกัน

GnuCash 3.8 หรือใหม่กว่า เมื่อเซิร์ฟเวอร์เขียนลงสมุดแล้ว สมุด จะมีเครื่องหมายฟีเจอร์ ("ใช้เครื่องหมายธรรมชาติในจำนวนงบประมาณ") ที่ GnuCash 3.8 แนะนำ และ GnuCash 3.0–3.7 ปฏิเสธ ที่จะเปิดสมุดที่มีเครื่องหมายฟีเจอร์ที่มันไม่รู้จัก GnuCash 3.8 และใหม่กว่าทำเครื่องหมายสมุดใดๆ ที่มีงบประมาณในลักษณะเดียวกันเมื่อเปิด ดังนั้นสิ่งนี้สำคัญเฉพาะถ้าคุณยังใช้ 3.x ที่เก่ากว่า เซิร์ฟเวอร์ ทดสอบกับ GnuCash 5.12

ชี้เซิร์ฟเวอร์ไปที่มัน

ด้วยชุดรวม เลือกสมุดในการตั้งค่าส่วนขยาย GnuCash ใน Claude Desktop จากนั้นรีสตาร์ท Claude Desktop ด้วยการติดตั้งจากการโคลน ตั้งค่า GNUCASH_BOOK_PATH เป็นพาธสัมบูรณ์ของสมุด ดู การใช้สมุดของคุณเอง

หรือ: เก็บสมุดใน PostgreSQL หรือ MySQL

GnuCash ยังสามารถเก็บสมุดในฐานข้อมูลแทนไฟล์ และ เซิร์ฟเวอร์ก็ให้บริการหนึ่งในนั้นด้วย ชี้ไปที่สตริงการเชื่อมต่อ แทนพาธ:

{
  "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"
  }
}

ติดตั้งไดรเวอร์พร้อมกับเซิร์ฟเวอร์ — postgres หรือ mysql (MariaDB ใช้ตัวเดียวกัน) จากภายในโคลนของคุณ (โฟลเดอร์ gnucash-mcp; ดู การติดตั้งจากซอร์ส):

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

สำหรับ MySQL / MariaDB สตริงการเชื่อมต่อคือ mysql+pymysql://user:password@localhost:3306/gnucash และส่วนเพิ่มเติม คือ [mysql]: uv tool install -e ".[mysql]" --reinstall รูปแบบ สั้นที่ GnuCash เขียนเอง mysql:// และ postgres:// ก็ใช้ได้เช่นกัน เซิร์ฟเวอร์ใช้ไดรเวอร์ที่ส่วนเพิ่มเติมติดตั้ง

ติดตั้งจากการโคลน ตามข้างต้น ไม่ใช่โดยชื่อ: ชื่อ gnucash-mcp บน PyPI เป็นของโปรเจกต์อื่น

เพื่อย้ายสมุดที่มีอยู่ข้าม: เปิดใน GnuCash ไฟล์ → บันทึกเป็น เลือก postgres หรือ mysql และกรอก รายละเอียดการเชื่อมต่อ (บน Debian/Ubuntu รายการเหล่านั้นต้องใช้ sudo apt install libdbd-pgsql or libdbd-mysql เช่นเดียวกับที่ SQLite3 ต้องใช้ libdbd-sqlite3; บิลด์ macOS และ Windows มาพร้อมทั้งสามตัว) เก็บไฟล์ — มันยังเป็นข้อมูลสำรองที่ดีของทุกอย่าง จนถึงช่วงเวลาที่คุณสลับ

สิ่งที่ควรรู้ก่อนสลับ:

• GNUCASH_BOOK_PATH และ GNUCASH_BOOK_URI เป็นแบบเอกสิทธิ์ ซึ่งกันและกัน — สมุดเป็นไฟล์หรือฐานข้อมูล และการตั้งค่าทั้งสอง เป็นข้อผิดพลาดเริ่มต้นแทนที่จะเป็นการเสี่ยงว่าบันทึกของคุณจะไปที่บัญชีใด
• GNUCASH_LOG_DIR กลายเป็นข้อกำหนด บันทึกการตรวจสอบและดีบัก ปกติอยู่ในโฟลเดอร์ข้างไฟล์สมุด สตริงการเชื่อมต่อไม่มี "ข้าง"
• หนึ่งสมุดต่อเซิร์ฟเวอร์ switch_book จับคู่กับชื่อไฟล์ ดังนั้น หลายสมุดยังคงเป็นฟีเจอร์ของไฟล์
• เซิร์ฟเวอร์หยุดการสำรองข้อมูล นี่คือการแลกเปลี่ยนที่แท้จริง: ตาข่ายนิรภัยอัตโนมัติมีอยู่เพราะมันสามารถสแนปช็อตไฟล์ได้ และมันไม่สามารถสแนปช็อตฐานข้อมูลของคุณได้ create_backup บอก อย่างนั้นแทนที่จะแสร้งทำ ตั้งค่า pg_dump หรือ mysqldump ตาม ตารางเวลาก่อนย้ายสมุดจริง — ดู docs/RESTORE_FROM_BACKUP.md
• รหัสผ่านของคุณถูกปกปิดทุกที่ที่เซิร์ฟเวอร์ระบุชื่อสมุด — ใน ผลลัพธ์เครื่องมือ ในส่วนหัวแดชบอร์ด และในบันทึกการตรวจสอบ — และ ในทุกข้อความแสดงข้อผิดพลาด บรรทัดบันทึก และข้อผิดพลาดเริ่มต้น รวมถึง ที่ไดรเวอร์ฐานข้อมูลเขียน รหัสผ่านที่ให้เป็นพารามิเตอร์คิวรี (?password=…, sslpassword=…) ถูกปกปิดในลักษณะเดียวกัน
• ใส่สตริงการเชื่อมต่อในบล็อก env ไม่ใช่บน บรรทัดคำสั่ง --book-uri ใช้ได้ แต่รหัสผ่านในบรรทัดคำสั่ง ปรากฏแก่ผู้ใช้ทุกคนของเครื่องในรายการกระบวนการ บน PostgreSQL คุณยัง ละรหัสผ่านออกจากสตริงทั้งหมดและให้ไดรเวอร์อ่าน PGPASSWORD หรือ ~/.pgpass

ทั้งสองภาษาได้รับการทดสอบโดยชุดทดสอบและ CI: PostgreSQL 16 และ MariaDB 11 แต่ละตัวกับเซิร์ฟเวอร์จริง

---

การเลือกชุดโมดูล

--modules=all เป็นค่าเริ่มต้นที่ง่าย — ทุกเครื่องมือ 86 ตัว สำหรับการใช้งานรายวันคุณอาจต้องการน้อยกว่านั้น เลือกบทบาทที่ ตรงกับวิธีที่คุณจะพูดคุยกับเซิร์ฟเวอร์ คุณยังสามารถเลือก โมดูลที่อยู่เบื้องหลังแต่ละบทบาทแยกกันเพื่อการตัดที่ละเอียดยิ่งขึ้น

บทบาท	สิ่งที่ให้คุณ	เครื่องมือ
core	พื้นฐานบัญชีแยกประเภท — บัญชี ธุรกรรม ยอดคงเหลือ สล็อต บันทึกการตรวจสอบ การสำรองข้อมูล งบดุล การกระทบยอด โหลดเสมอ	29
bookkeeper	ทุกอย่างยกเว้นธุรกิจ: รายงาน งบประมาณ ธุรกรรมตามกำหนด ราคา และล็อตการลงทุน ชุดการเงินส่วนบุคคล	30
investor	การติดตามต้นทุนและจัดการราคาเท่านั้น (ชุดย่อยของ bookkeeper)	13
business	ลูกค้า ซัพพลายเออร์ และพนักงาน ใบแจ้งหนี้ บิล ใบสำคัญ และใบลดหนี้ ภาษีขาย เงื่อนไขการชำระเงิน งาน และรายงานซัพพลายเออร์	27

เลือกหนึ่งหรือมากกว่า คั่นด้วยเครื่องหมายจุลภาค:

"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 จะถูกเพิ่มเสมอ freelancer และ business_complete, ชื่อที่เวอร์ชัน 1.4 ใช้ ยังคงรองรับและหมายถึง business โมดูล เบื้องหลังแต่ละบทบาท (reconciliation, reporting, budgets, scheduling, tax_lots, portfolio, ฯลฯ) สามารถเลือกได้ทีละตัวเช่นกัน — รัน uv run gnucash-mcp --help จาก repo เพื่อดูเมนูเต็ม

---

สิ่งที่คุณสามารถขอให้มันทำได้

การแนะนำแบบไม่ครบถ้วน คุณสามารถเรียบเรียงสิ่งเหล่านี้ได้อย่างเป็นธรรมชาติ — ผู้ช่วยจะแปลให้

การบันทึกใบแจ้งยอดทั้งใบ

"นี่คือใบแจ้งยอดบัญชีเดือนสิงหาคมของฉัน" (แนบ PDF)

ตรวจสอบ 31 รายการเทียบกับบัญชีของคุณ: 24 รายการใหม่, 6 รายการ ถูกบันทึกแล้ว (เคลมแล้ว), 1 รายการต้องตรวจสอบ — นี่คือการเปรียบเทียบ ยืนยันแล้วฉันจะลงรายการทั้งเดือน: บันทึก, จัดหมวดหมู่, และ กระทบยอดกับยอดปิดบัญชีในขั้นตอนเดียว

ใบแจ้งยอดหนึ่งใบ, การเรียกสองครั้ง, บัญชีที่ตรงกัน การทดลองแบบแห้งจะจัดหมวดหมู่ ทุกบรรทัดพร้อมหลักฐานก่อนที่จะเขียนอะไร และการยืนยันจะปฏิเสธทั้งชุด แทนที่จะลงเดือนที่ไม่ตรงกัน

การบันทึกรายการกิจกรรม

"ฉันใช้จ่าย $47.50 ที่ Safeway วันนี้สำหรับของชำ จ่ายด้วยบัตร Visa ของฉัน"

บันทึกแล้ว: $47.50 จาก Credit Card:Visa ไปยัง Expenses:Groceries เมื่อวันที่ 30 เม.ย. 2026 คำอธิบาย: "Safeway"

การตั้งค่าบิลที่เกิดซ้ำ

"ตั้งค่าค่าเช่าของฉันเป็นบิลที่เกิดซ้ำ $1,850 ในวันที่ 1 ของทุกเดือนจากบัญชีเงินฝาก"

สร้างรายการที่กำหนดเวลาไว้ "ค่าเช่ารายเดือน": $1,850 ต่อเดือน จาก Assets:Checking ไปยัง Expenses:Rent ครบกำหนดครั้งถัดไป: 1 พ.ค. 2026

การติดตามการลงทุน

"ฉันซื้อ VTSAX มูลค่า $1,000 ที่ $170.99/หุ้น ในบัญชี 401(k) ของฉัน"

บันทึกการซื้อ VTSAX: 5.85 หุ้น ที่ $170.99/หุ้น ต้นทุน รวม: $1,000.00 สร้างล็อตสำหรับการติดตามกำไร/ขาดทุนจากทุน เมื่อคุณขายในที่สุด

การออกใบแจ้งหนี้ให้ลูกค้า

"สร้างลูกค้าชื่อ Acme Corp และออกใบแจ้งหนี้ $1,500 สำหรับงานให้คำปรึกษา"

สร้างลูกค้า Acme Corp (id 000005) และใบแจ้งหนี้ 000019: 1× Consulting ที่ $1,500.00 = $1,500.00 ยังไม่ปิด บอกฉันเมื่อ คุณพร้อมที่จะลงรายการ

หากคุณเปิดใบแจ้งหนี้ที่ลงรายการผ่านเซิร์ฟเวอร์ในกล่องโต้ตอบ Process Payment ของ GnuCash ให้ตั้งค่าบัญชี "Post To" เป็นบัญชีลูกหนี้ของใบแจ้งหนี้ก่อน: กล่องโต้ตอบจะแสดงเฉพาะเอกสารที่ลงรายการไปยังบัญชีที่เลือกเท่านั้น

การออกใบแจ้งหนี้สกุลเงินต่างประเทศ

"ออกใบแจ้งหนี้ Berlin Digital €4,200 สำหรับค่าจ้างรายไตรมาส 1 ครบกำหนดใน 30 วัน"

สร้างใบแจ้งหนี้ EUR 000020 สำหรับ Berlin Digital GmbH: 1× Q1 Retainer ที่ EUR 4,200 = EUR 4,200 Net 30 เมื่อพวกเขา จ่าย ฉันจะบันทึกกำไร/ขาดทุนจากอัตราแลกเปลี่ยนที่เกิดขึ้นจริงไปยัง บัญชี FX ของคุณโดยอัตโนมัติ

การถามคำถาม

"ฉันใช้จ่ายกับแต่ละผู้ขายเท่าไหร่ในปีนี้?"

Office Depot: $2,340 (4 บิล, $0 ค้างชำระ) CloudHost Inc: $1,200 (2 บิล, $600 ค้างชำระ) Legal Associates: $3,500 (1 บิล, $3,500 ค้างชำระ) รวมที่ออกใบแจ้งหนี้ $7,040 / จ่ายแล้ว $2,940 / ค้างชำระ $4,100

การกระทบยอด

"ช่วยฉันกระทบยอดบัญชีเงินฝากกับใบแจ้งยอดเดือนเมษายน"

[แนะนำคุณตลอดกระบวนการ: ดึงรายการที่ยังไม่กระทบยอด ถามคุณ เพื่อยืนยันรายการที่เคลียร์แล้ว คำนวณยอดคงเหลือ ต่อเนื่อง ทำเครื่องหมายรายการที่ตรงกันว่ากระทบยอดแล้ว ปล่อย รายการที่ไม่ตรงกันให้คุณตรวจสอบ]

---

ความเป็นส่วนตัวและความปลอดภัย

ไฟล์บัญชีของคุณไม่เคยออกจากเครื่องของคุณ เซิร์ฟเวอร์นี้เป็น กระบวนการท้องถิ่นที่อ่านและเขียนไฟล์ท้องถิ่น ผู้ช่วย AI ที่คุณกำลังพูดคุยด้วย (Claude Desktop ฯลฯ) จะเห็น ผลลัพธ์ของการเรียกใช้เครื่องมือของคุณ — เนื้อหาเดียวกับที่คุณเห็นบน หน้าจอ — แต่ไฟล์เองยังคงอยู่ที่เดิม

ทุกการเขียนถูกบันทึก ร่องรอยการตรวจสอบที่มนุษย์อ่านได้อยู่ ข้างไฟล์บัญชีของคุณที่ <your-book>.gnucash.mcp/audit/, หนึ่งไฟล์บันทึกต่อวัน คุณสามารถอ่านได้ตลอดเวลาเพื่อดู สิ่งที่เปลี่ยนแปลงและเมื่อใด ตัวอย่างรายการ:

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

การสำรองข้อมูลอัตโนมัติ ก่อนการเขียนครั้งแรกของแต่ละเซสชัน (และอีกครั้งเมื่อเซสชันที่ยาวนานข้ามเข้าสู่ช่วงการสำรองข้อมูลใหม่) เซิร์ฟเวอร์จะสแนปช็อตบัญชีของคุณไปยัง <your-book>.gnucash.mcp/backups/ — ดังนั้นหากมีอะไรผิดพลาด คุณสามารถย้อนกลับไปยังสถานะที่รู้ว่าดีได้โดยไม่ต้อง พึ่งพา Time Machine หรือนิสัยของคุณเอง การสำรองข้อมูลจะถูก ตรวจสอบด้วย PRAGMA integrity_check ก่อนที่จะประกาศว่า ถูกต้อง และจะข้ามไปเมื่อบัญชีไม่มีการเปลี่ยนแปลงตั้งแต่ สแนปช็อตครั้งล่าสุด ดู docs/RESTORE_FROM_BACKUP.md สำหรับขั้นตอนการย้อนกลับ

การอ่านการประทับเวลา: ชื่อไฟล์ สำรองข้อมูลมีการประทับเวลา UTC (ปลอดภัยต่อระบบไฟล์และไม่คลุมเครือเมื่อเดินทางข้ามเขตเวลา และ DST); บันทึกการตรวจสอบและดีบักใช้ไฟล์รายวันที่ ระบุวันที่ท้องถิ่น ซึ่งตรงกับวิธีที่คุณค้นหา "เกิดอะไรขึ้น วันอังคาร" ใกล้เที่ยงคืนสิ่งเหล่านี้อาจแตกต่างกันหนึ่งวัน — โปรดจำไว้เมื่อจับคู่การสำรองข้อมูลกับบันทึกของวัน

รายการที่กระทบยอดแล้วได้รับการปกป้อง เซิร์ฟเวอร์ปฏิเสธที่จะ ลบหรือแก้ไขรายการที่กระทบยอดแล้วโดยไม่มีการแทนที่อย่างชัดเจน ดังนั้นพรอมต์ที่ไม่ระมัดระวังไม่สามารถทำให้การกระทบยอดธนาคาร ครั้งล่าสุดของคุณเป็นโมฆะอย่างเงียบๆ ได้

การยกเลิก ≠ การลบ เมื่อคุณบอก AI ให้ "ยกเลิกรายการนี้" มันจะใช้การยกเลิกทางบัญชีที่เหมาะสมของ GnuCash — เก็บรักษารายการไว้สำหรับร่องรอยการตรวจสอบโดยมีค่าเป็นศูนย์ การลบเป็นตัวเลือกที่ทำลายล้าง AI จะบอกคุณ ว่ากำลังทำแบบไหน

ข้อจำกัดความรับผิดชอบ: ซอฟต์แวร์นี้ให้บริการ "ตามสภาพ" ภายใต้ สัญญาอนุญาต MIT โดยไม่มีการรับประกันใดๆ ผู้เขียนไม่รับผิดชอบต่อการสูญเสียข้อมูล ความเสียหาย หรือ ความคลาดเคลื่อนทางการเงินที่เกิดจากการใช้งาน คุณเป็นผู้รับผิดชอบ แต่เพียงผู้เดียวในการรักษาการสำรองข้อมูลของคุณเองและตรวจสอบ ความถูกต้องของบัญชีของคุณ

---

ข้อจำกัดที่ทราบ

• อย่าแก้ไขใน GnuCash เดสก์ท็อปและผ่านเซิร์ฟเวอร์พร้อมกัน เซิร์ฟเวอร์เคารพล็อกของ GnuCash แต่ไม่ได้ถือล็อกของตัวเอง (มันเปิดบัญชีทีละการเรียก) ดังนั้น GnuCash จะไม่เตือนคุณ ว่าเซิร์ฟเวอร์กำลังใช้บัญชีอยู่
• บัญชีที่เปิด "Use Trading Accounts": รายการข้ามสกุลเงิน หรือสินค้าโภคภัณฑ์ รวมถึงการซื้อหุ้นและกองทุน จะถูกปฏิเสธ เพราะเซิร์ฟเวอร์ยังไม่สามารถเขียน trading splits วิธีที่ GnuCash ทำได้ ป้อนรายการเหล่านั้นใน GnuCash เดสก์ท็อป; ทุกอย่างในสกุลเงินเดียวทำงานตามปกติ
• GnuCash 3.8 หรือใหม่กว่า บัญชีที่เซิร์ฟเวอร์เขียนลงไป มีเครื่องหมายคุณสมบัติที่ GnuCash 3.0–3.7 ไม่สามารถเปิดได้
• การใช้จ่ายและรายได้ในสกุลเงินต่างประเทศ จะถูกประเมินมูลค่า ที่อัตราปิดของแต่ละเดือนในรายงานการใช้จ่ายและรายได้ ไม่ใช่ ที่เงินสดที่จ่ายไป; cash_flow รายงานเงินสด

รายการเต็มอยู่ใน CHANGELOG.md

---

การจำกัดสิ่งที่ AI สามารถเห็นได้

คำอธิบายของแต่ละเครื่องมืออยู่ในระบบพรอมต์ของ AI ซึ่ง ใช้บริบทในทุกข้อความ การจำกัดชุดเครื่องมือให้เหลือเฉพาะที่ คุณใช้จริงทำให้การสนทนาแต่ละครั้งถูกลง ดู การเลือกชุดโมดูล ด้านบนสำหรับ สี่บทบาท (core, bookkeeper, investor, business)

คุณยังสามารถตั้งค่า GNUCASH_MCP_MODULES=core,bookkeeper เป็น ตัวแปรสภาพแวดล้อมแทน --modules=... ในอาร์กิวเมนต์ JSON

---

สิ่งใหม่ใน v1.5.0

• บัญชีในฐานข้อมูล ชี้เซิร์ฟเวอร์ไปยังบัญชีที่ GnuCash เก็บ ใน PostgreSQL หรือ MySQL/MariaDB ไม่ใช่แค่ไฟล์ SQLite — ดู หรือ: เก็บบัญชีใน PostgreSQL หรือ MySQL การสนับสนุน PostgreSQL ได้รับการสนับสนุนโดย @vchatela
• ทุกอย่างถูกเก็บในแบบที่ GnuCash เดสก์ท็อปเก็บ รายการที่กำหนดเวลาไว้ทำงานใน Since Last Run ของเดสก์ท็อป งบประมาณ ใบแจ้งหนี้ ใบลดหนี้ การยกเลิก และราคาอ่านเหมือนกันทั้งสองฝั่ง และยอดรวมใบแจ้งหนี้ตรงกับของ GnuCash ถึงเซนต์ อัปเกรด จาก 1.4? อ่าน คู่มือการอัปเกรด ก่อน
• การชำระล่วงหน้า บันทึกการจ่ายเกินของลูกค้าหรือผู้ขายเป็น เงินที่ถือไว้สำหรับพวกเขา ชำระใบแจ้งหนี้ภายหลังจากเงินนั้น และยกเลิกการลงรายการใบแจ้งหนี้ที่ชำระแล้วโดยไม่สูญเสียการชำระเงิน
• ลิงก์ Num และเอกสาร ในทุกเครื่องมือรายการ โดยใช้ หมายเลขเป็นตัวตรวจสอบรายการซ้ำ
• แผนผังผังบัญชีของคุณ บนแดชบอร์ด เพื่อให้ ผู้ช่วยรู้ว่าทุกบัญชีอยู่ที่ไหนก่อนที่จะถาม
• บัญชีตัวอย่างที่สร้างจากซอร์ส แต่ละบัญชีตรวจสอบกับ แนวปฏิบัติทางภาษีของประเทศของตัวเอง (US/Washington, Germany, China) และเป็นปัจจุบันจนถึงวันที่สร้าง

รุ่นก่อนหน้านี้อยู่ใน CHANGELOG.md

---

การแก้ไขปัญหา

ไม่มีไอคอน 🔨 ค้อน หรือ "tool not found"

• ออกจาก Claude Desktop โดยสมบูรณ์ แล้วเปิดใหม่ (การปิด หน้าต่างไม่เพียงพอ — คุณต้องออกจากแอปพลิเคชัน)
• ตรวจสอบว่าเส้นทางในคอนฟิกของคุณเป็นเส้นทางสัมบูรณ์และถูกต้อง
• ตรวจสอบ JSON สำหรับเครื่องหมายจุลภาคต่อท้าย — มันทำให้คอนฟิก เสียหายอย่างเงียบๆ

"Book not found"

• ใช้เส้นทางสัมบูรณ์ ไม่ใช่ ~ หรือเส้นทางสัมพัทธ์
• Mac/Linux: /Users/yourname/Documents/book.gnucash
• Windows: C:\\Users\\yourname\\Documents\\book.gnucash (แบ็กสแลชซ้ำ — ข้อกำหนด JSON)

"Cannot open book" / ข้อผิดพลาด piecash

• ยืนยันว่าบัญชีของคุณอยู่ในรูปแบบ SQLite ไม่ใช่ XML
• ตรวจสอบให้แน่ใจว่า GnuCash ไม่ได้เปิดอยู่กับบัญชีเดียวกัน — ล็อกไฟล์ เซิร์ฟเวอร์เคารพล็อกของ GnuCash แต่จงใจไม่ถือล็อกของตัวเอง (มันถือบัญชีทีละการเรียก) ดังนั้น GnuCash จะเปิดบัญชีที่เซิร์ฟเวอร์ใช้อยู่โดยไม่มีการเตือน อย่า แก้ไขทั้งสองพร้อมกัน
• ลองเปิดบัญชีใน GnuCash เองเพื่อตรวจสอบว่าไม่เสียหาย

Docker: "both GNUCASH_BOOK_PATH and GNUCASH_BOOK_URI are set"

อิมเมจมาพร้อมกับ GNUCASH_BOOK_PATH ชี้ไปที่บัญชีตัวอย่าง ในตัว หากต้องการให้บริการบัญชีฐานข้อมูลจากมัน ให้ล้างค่าเริ่มต้นนั้น บนบรรทัดคำสั่ง (-e GNUCASH_BOOK_PATH=) ข้าง GNUCASH_BOOK_URI ของคุณ; เพื่อให้บริการไฟล์ที่เมานต์ ให้ตั้งค่า GNUCASH_BOOK_PATH เป็นเส้นทางที่เมานต์และรันคอนเทนเนอร์เป็น ผู้ใช้ที่เป็นเจ้าของไฟล์ (--user "$(id -u):$(id -g)")

"Account not found"

• ใช้เส้นทางบัญชีเต็ม: Expenses:Groceries, ไม่ใช่แค่ Groceries
• หรือขอให้ผู้ช่วยแสดงรายการบัญชี: "แสดงรายการบัญชีของฉัน"

หลายกระบวนการเซิร์ฟเวอร์หลังรีสตาร์ทไคลเอนต์

Claude Desktop (และไคลเอนต์ MCP อื่นๆ บางตัว) อาจสร้าง สำเนาเซิร์ฟเวอร์สองหรือสามชุดชั่วคราวเมื่อเปิดใหม่ นี่คือ พฤติกรรมของไคลเอนต์ ไม่ใช่บั๊กของเซิร์ฟเวอร์ และส่วนใหญ่ไม่เป็นอันตราย: เซิร์ฟเวอร์เปิดบัญชีของคุณต่อคำขอและปล่อย ล็อกไฟล์ระหว่างการเรียก ดังนั้นกระบวนการที่ทับซ้อนกันจะแข่งขันกัน เพียงชั่วครู่ หากคุณเห็นข้อผิดพลาด Lock on the file ถาวร หลังรีสตาร์ทไคลเอนต์ ให้ออกจากไคลเอนต์โดยสมบูรณ์ ยืนยันด้วย pgrep -fl gnucash-mcp ว่าไม่มีกระบวนการหลงเหลือ แล้วเปิดใหม่

มีบางอย่างผิดพลาด

• เปิดบันทึกการตรวจสอบที่ <your-book>.gnucash.mcp/audit/ — ทุกการเขียนตั้งแต่เซิร์ฟเวอร์รันครั้งแรกอยู่ที่นั่นพร้อม รายละเอียดก่อน/หลัง
• หากคุณต้องการย้อนกลับ docs/RESTORE_FROM_BACKUP.md อธิบายขั้นตอน

---

สนับสนุนโครงการ

หาก gnucash-mcp มีประโยชน์สำหรับคุณ โปรดพิจารณา ซื้อกาแฟให้ฉัน มันช่วย ให้การพัฒนาดำเนินต่อไป

---

สำหรับนักพัฒนา

คู่มือผู้มีส่วนร่วมและบันทึกการออกแบบอยู่ใน CLAUDE.md การปฐมนิเทศอย่างรวดเร็ว:

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/

คำสั่ง gnucash-mcp ที่ติดตั้งจะติดตาม clone ของคุณแบบสด: มัน ให้บริการสาขาที่ checkout อยู่ ดังนั้นการสลับสาขา จะสลับโค้ดที่ให้บริการในการรีสตาร์ทครั้งถัดไป — สะดวกสำหรับการทดสอบ ควรจำไว้เมื่อคุณลืมว่าอยู่กลางสาขา หากต้องการรัน checkout ที่แตกต่าง (worktree ที่สอง) โดยไม่แตะต้อง การติดตั้ง uv run --directory PATH gnucash-mcp ยังคงรัน ไดเรกทอรีใดก็ตามที่คุณชี้ไป

เซิร์ฟเวอร์สร้างบน piecash (อินเทอร์เฟซ Python กับบัญชี SQLite ของ GnuCash) และ MCP Python SDK ประมาณ 18,000 บรรทัดของซอร์ส Python, 20,000 บรรทัดของการทดสอบ แบบโมดูลาร์เพื่อให้โมดูลที่ปิดใช้งานไม่มีค่าใช้จ่ายที่รันไทม์

สัญญาอนุญาต

MIT

กิตติกรรมประกาศ

• GnuCash — ซอฟต์แวร์บัญชี ฟรีและโอเพนซอร์สที่เซิร์ฟเวอร์นี้ทำให้สามารถสนทนาได้
• piecash — อินเทอร์เฟซ Python กับบัญชี SQLite ของ GnuCash
• MCP Python SDK — การใช้งาน Model Context Protocol