Beancount MCP: اتصال دفتر کل خود به دستیاران هوش مصنوعی

از دستیار هوش مصنوعی خود بپرسید ماه گذشته چقدر هزینه کرده‌اید، کدام حساب‌ها نیاز به تطبیق دارند، یا یک تراکنش متعلق به کجاست. Beancount MCP به آن دسترسی به پرس‌وجوها، حساب‌ها و فایل‌های منبع دفتر کل میزبان‌شده شما می‌دهد، بنابراین می‌تواند از روی دفترهای شما کار کند و شواهد پشت پاسخ خود را نشان دهد.

با مجوز نوشتن، دستیار همچنین می‌تواند تراکنش‌ها را اضافه کند و فایل‌های دفتر کل را به‌روزرسانی کند. می‌توانید از آن بخواهید ویرایش‌های پشتیبانی‌شده را پیش‌نمایش بگیرد، ورودی‌های پیشنهادی را بررسی کند و پس از تغییر، دفتر کل را بررسی کند.

MCP مخفف Model Context Protocol است: یک استاندارد برای اتصال برنامه‌های هوش مصنوعی به ابزارها و داده‌های خارجی. این اتصال با دفترهای کل میزبانی‌شده در Beancount.io کار می‌کند. پاسخ‌های دستیار شما تراکنش‌ها و قیمت‌های ثبت‌شده در آنجا را منعکس می‌کنند؛ اتصال MCP به‌طور خودکار آن records را به‌روز نمی‌کند.

کلاینت هوش مصنوعی خود را متصل کنید​

از کلاینتی استفاده کنید که از MCP راه دور از طریق Streamable HTTP پشتیبانی می‌کند. آدرس سرور این است:

https://beancount.io/api-gateway/mcp

Claude Code​

سرور را از ترمینال خود اضافه کنید:

claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

Claude Code را باز کنید، /mcp را اجرا کنید، beancount را انتخاب کنید و جریان احراز هویت آن را دنبال کنید. به Beancount.io وارد شوید و مجوزهای درخواستی را بررسی کنید. برای تأیید اتصال به /mcp برگردید. برای جزئیات خاص کلاینت، دستورالعمل‌های MCP کلود Code را ببینید.

صفحه رضایت به شما اجازه می‌دهد دسترسی را به یک دفتر کل محدود کنید یا به‌صراحت همه دفترهای کل قابل دسترس را انتخاب کنید. محدودیت تک‌دفتری یک نقطه شروع مفید است. با دسترسی گسترده‌تر، به دستیار بگویید از کدام دفتر کل استفاده کند، مانند alice/personal؛ ابزارهای دفتر کل باید هدف خود را در هر تماس شناسایی کنند.

Claude Desktop و Claude روی وب​

Customize → Connectors را باز کنید، Add custom connector را انتخاب کنید، آدرس سرور را وارد کنید و حساب Beancount.io خود را متصل کنید. اتصال را برای گفتگویی که می‌خواهید از آن استفاده کنید فعال کنید. حساب‌های سازمانی ممکن است ابتدا به یک مالک برای افزودن اتصال نیاز داشته باشند. راهنمای اتصالات راه دور کلود را دنبال کنید.

Cursor​

سرور را به ~/.cursor/mcp.json شخصی خود اضافه کنید:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

وقتی Cursor آن را درخواست کرد، ورود OAuth را تکمیل کنید، سپس بررسی کنید که ابزارهای سرور در دسترس هستند. مستندات MCP کرسور پیکربندی و تنظیمات تأیید ابزار را پوشش می‌دهد.

کلیدهای API شخصی​

برای کلاینتی که اعتبارنامه‌های Bearer را می‌پذیرد، می‌توانید یک کلید API شخصی در Settings → Personal access tokens ایجاد کنید. ایجاد کلید به یک پلن پولی Beancount.io نیاز دارد. برای پرس‌وجوها ledger.read را انتخاب کنید، optionally کلید را به یک دفتر کل محدود کنید و وقتی نشان داده شد آن را کپی کنید. هدر مجوز کلاینت خود را به‌صورت Authorization: Bearer YOUR_KEY با استفاده از تنظیمات اعتبارنامه خصوصی آن پیکربندی کنید.

کلید را از پیکربندی پروژه مشترک دور نگه دارید. کلاینت‌های OAuth اعتبارنامه‌ها را از طریق جریان ورود خود مدیریت می‌کنند؛ نیازی به ایجاد کلید شخصی برای آن مسیر ندارید.

با یک سؤال هزینه شروع کنید​

پس از اتصال این را امتحان کنید و نام دفتر کل را با نام خود جایگزین کنید:

از alice/personal استفاده کنید. حساب‌ها و ارزهای آن را شناسایی کنید، سپس هزینه‌های آگوست 2026 را بر اساس حساب خلاصه کنید. محدوده تاریخ و BQL پشت هر مجموع را نشان دهید، ارزها را جدا نگه دارید و هر خطای اعتبارسنجی دفتر کل را گزارش دهید. چیزی را تغییر ندهید.

دستیار می‌تواند دفترهای کل شما را با listLedgers کشف کند، نام حساب‌های شما را از طریق getLedgerContext یاد بگیرد و runBqlQueryStructured را برای نتایج پرس‌وجوی تایپ‌شده اجرا کند. checkLedger خطاهای اعتبارسنجی، تعداد ورودی‌ها و آخرین commit را برمی‌گرداند.

یک پاسخ مفید شامل دفتر کل، دوره، ارزها، مجموع‌ها و پرس‌وجوهای پشتیبان است. برای یک سؤال ارزش خالص، همچنین روش ارزیابی و تاریخ قیمت‌های استفاده‌شده را بخواهید. تراکنش‌های از دست رفته یا قیمت‌های قدیمی می‌توانند پاسخ را تغییر دهند حتی وقتی دفتر کل اعتبارسنجی را پاس می‌کند.

افزودن تراکنش با پیش‌نمایش​

برای ورودی‌های جدید، appendLedgerText متن معمولی Beancount را می‌پذیرد و دستورالعمل‌ها را با استفاده از پیکربندی دفتر کل شما به فایل‌ها هدایت می‌کند. گزینه dry_run آن یک diff و خطاهای اعتبارسنجی پیش‌بینی‌شده را قبل از commit برمی‌گرداند.

برای مثال:

یک خرید قهوه به مبلغ 4.50 دلار آمریکا به تاریخ 15 سپتامبر 2026 آماده کنید، از Assets:Cash پرداخت شده و در Expenses:Food دسته‌بندی شده. بررسی کنید که آن حساب‌ها وجود دارند و ابتدا به دنبال یک تراکنش مطابق بگردید. از appendLedgerText با dry_run: true استفاده کنید، ورودی پیشنهادی و diff فایل را نشان دهید و منتظر تأیید من بمانید.

با باز بودن آن حساب‌ها، ورودی پیشنهادی به این شکل خواهد بود:

2026-09-15 * "Cafe" "Coffee"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD

از نام حساب‌های دفتر کل خود استفاده کنید، سپس بررسی را کامل کنید:

1. تاریخ، مبلغ، حساب‌ها و فایل مقصد را در پیش‌نمایش بررسی کنید.
2. تغییر دقیقی را که می‌خواهید دستیار اعمال کند تأیید کنید.
3. از آن بخواهید checkLedger را اجرا کند و commit حاصل و هر خطا را گزارش دهد.

appendLedgerText به‌طور پیش‌فرض خطاهای اعتبارسنجی جدید را رد می‌کند. تغییرات فایل عمومی از editLedgerFiles استفاده می‌کنند که می‌تواند فایل‌ها را در یک commit Git ایجاد، جایگزین، به‌روزرسانی یا حذف کند. پیش‌نمایش آن نیز یک diff و خطاهای پیش‌بینی‌شده را گزارش می‌دهد. نتیجه را بررسی کنید و پس از نوشتن checkLedger را اجرا کنید: یک commit موفق می‌تواند همچنان شامل خطاهای حسابداری باشد.

استفاده از یک گردش کار برای دفترداری دوره‌ای​

سرور همچنین اعلان‌های MCP قابل استفاده مجدد ارائه می‌دهد. کلاینت‌های با پشتیبانی اعلان، آنها را در فرمان یا انتخابگر اعلان خود نمایش می‌دهند:

این اعلان‌ها دستیار را در یک رویه راهنمایی می‌کنند. آنها صرفاً به این دلیل که شما آنها را انتخاب می‌کنید یک کار حسابداری اجرا نمی‌کنند و مجوزهای اضافی اعطا نمی‌کنند.

تطبیق به یک صورت و مانده پایانی نیاز دارد. یک نتیجه اعتبارسنجی تمیز به تنهایی نمی‌تواند ثابت کند که هر تراکنش ثبت شده است. از دستیار بخواهید هر چیزی را که نتوانسته تأیید کند شناسایی کند و آن سؤالات را در گزارش قابل مشاهده بگذارد.

برای واردات بانکی، ابتدا بانک را در Beancount.io پیوند دهید. خواندن جزئیات اتصال به دسترسی مدیریتی نیاز دارد؛ ارسال تراکنش‌های مرحله‌بندی‌شده به مجوز نوشتن و دسترسی مناسب به آن اتصال بانکی نیاز دارد. قبل از مجوز ارسال، دسته‌ها و موارد تکراری پیشنهادی را بررسی کنید.

درک دسترسی و پردازش داده​

مجوزهای اتصال تعیین می‌کنند که دستیار چه کاری می‌تواند انجام دهد:

دسترسی موجود شما به هر دفتر کل همچنان اعمال می‌شود. محدود کردن یک اعتبارنامه به یک دفتر کل از هدف قرار دادن دفتر دیگری توسط تماس‌های دفتر کل جلوگیری می‌کند؛ یک اعتبارنامه بدون محدودیت می‌تواند بین دفترهای کل که به آنها دسترسی دارید انتخاب کند. کلاینت OAuth انتخاب می‌کند کدام مجوزها را درخواست کند، بنابراین قبل از تأیید صفحه رضایت را بخوانید.

سرور MCP یک گفتگوی تأیید انسانی نمایش نمی‌دهد. تنظیمات کلاینت شما تعیین می‌کند چه زمانی قبل از فراخوانی یک ابزار بپرسد، و پیش‌نمایش‌ها باید صریحاً درخواست شوند. گردش‌های کاری نوشتن ارائه‌شده به دستیار دستور می‌دهند منتظر تأیید بماند. یک اعتبارنامه محدود به ledger.read یک مرز اجباری فراهم می‌کند وقتی تحلیل بدون نوشتن می‌خواهید.

نتایج ابزار، از جمله تراکنش‌های پرس‌وجوشده و فایل‌هایی که دستیار می‌خواند، وارد بافت کلاینت هوش مصنوعی شما می‌شوند و ممکن است توسط ارائه‌دهنده مدل آن پردازش شوند. Beancount.io دفتر کل، تاریخچه Git و سوابق عملیاتی شما را نگه می‌دارد. یک اتصال MCP بدون حالت، وعده عدم نگهداری داده نیست؛ سیاست‌های داده کلاینت و ارائه‌دهنده شما نیز اعمال می‌شوند.

کلیدهای API شخصی لغوشده در درخواست‌های بعدی رد می‌شوند. توکن‌های دسترسی OAuth معمولاً یک ساعت دوام می‌آورند؛ لغو یک توکن بازخوانی، توکن دسترسی قبلاً صادرشده را فوراً بی‌اعتبار نمی‌کند. دسترسی به دفتر کل زمانی که عملیات محافظت‌شده اجرا می‌شوند دوباره بررسی می‌شود.

سؤالات رایج​

آیا این دفتر کل را روی لپ‌تاپ من باز می‌کند؟

نقطه پایانی میزبانی‌شده بر روی دفتر کل Beancount.io شما عمل می‌کند. یک فایل .bean محلی را باز نمی‌کند و نیازی به تب مرورگر Fava باز ندارید.

این چه تفاوتی با دستیار هوش مصنوعی داشبورد دارد؟

داشبورد رابط چت خود را فراهم می‌کند. MCP قابلیت‌های دفتر کل را از یک کلاینت هوش مصنوعی خارجی، با گفتگو، مدل و تنظیمات تأیید آن کلاینت در دسترس قرار می‌دهد.

چرا می‌توانم یک ابزار را ببینم اما نمی‌توانم از آن استفاده کنم؟

کاتالوگ ابزار شامل عملیاتی است که اعتبارنامه شما ممکن است اجازه ندهد. خطا و مجوزهای اعطاشده را بررسی کنید. یک اعتبارنامه بدون محدودیت نیز برای ابزارهای دفتر کل به یک هدف دفتر کل صریح نیاز دارد.

دفتر کل خود را متصل کنید و با یک سؤال شروع کنید که می‌توانید آن را با دفترهای خود تأیید کنید. پرس‌وجو را با پاسخ نگه دارید، سپس وقتی می‌خواهید در نگهداری خود دفتر کل کمک بگیرید، مجوزهای نوشتن را اضافه کنید.