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

Web Beancount سرور MCP را راه‌اندازی می‌کند — از Claude، Cursor و هر ابزار هوش مصنوعی که پیش‌تر استفاده می‌کنید با دفتر کل خود گفت‌وگو کنید

داده‌های حسابداری شما با جریان کاری هوش مصنوعی‌تان دیدار می‌کند. بدون کپی‌وچسباندن. بدون خروجی‌گرفتن. فقط بپرسید.

امروز، Web Beancount از سرور Beancount MCP رونمایی می‌کند — یک نقطه‌ی پایانی Model Context Protocol (MCP) که به شما امکان می‌دهد دفتر کل Beancount خود را مستقیماً به Claude Desktop، Claude Code، Cursor، Windsurf یا هر کلاینت هوش مصنوعی دیگر سازگار با MCP متصل کنید. برای نخستین بار، کاربران حرفه‌ای می‌توانند پرسش‌های حسابداری بپرسند، پرس‌وجوهای BQL را اجرا کنند و حتی فایل‌های دفتر کل را از درون ابزارهای هوش مصنوعی که پیش‌تر در آن‌ها کار می‌کنند ویرایش کنند — بدون جابه‌جایی میان زبانه‌ها یا ترک جریان کاری خود.

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

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

بپرسید «امروز ارزش خالص دارایی من چقدر است؟» و پاسخی زنده برگرفته از دفتر کل واقعی خود دریافت کنید
خلاصه‌ای از هزینه‌های ماه گذشته درخواست کنید و بگذارید هوش مصنوعی پرس‌وجوی BQL را برایتان بنویسد
به هوش مصنوعی بگویید یک تراکنش اضافه کند و ببینید که تغییر را در مخزن git دفتر کل شما ثبت می‌کند
فایل‌های .beancount خود را بدون آنکه هرگز ویرایشگرتان را ترک کنید مرور و مطالعه کنید

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

سرور Beancount MCP از امروز برای همه‌ی کاربران Web Beancount در دسترس است.

شروع کنید

سرور Beancount MCP فعال است. آن را در کمتر از یک دقیقه به کلاینت هوش مصنوعی خود اضافه کنید.

نشانی سرور MCP

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

Claude Code (توصیه‌شده — جریان کامل OAuth 2.1، بدون نیاز به توکن)

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

در نخستین استفاده، Claude Code یک پنجره‌ی مرورگر باز می‌کند. درخواست مرورگر جایی است که شما انتخاب می‌کنید کدام دفتر کل متصل شود — یک‌بار تأیید کنید، و اعتبارنامه‌ها به‌طور خودکار تازه می‌شوند. بیش از یک دفتر کل دارید؟ سرور را دوباره با نامی متفاوت اضافه کنید (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) و دفتر کل دیگر را در درخواست خودش مجاز کنید.

Claude Desktop / Cursor / Windsurf / Zed

سرور را به پیکربندی MCP کلاینت خود اضافه کنید (claude_desktop_config.json یا معادل آن). کلاینت‌های دارای پشتیبانی OAuth 2.1 در نخستین استفاده همان درخواست مرورگر را باز می‌کنند — دفتر کل خود را همان‌جا انتخاب کنید:

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

اگر کلاینت شما هنوز از جریان OAuth پشتیبانی نمی‌کند، یک توکن ایستا (محدود به یک دفتر کل) از تنظیمات حساب beancount.io خود بسازید و آن را به‌عنوان یک هدر ارسال کنید:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

حساب Web Beancount ندارید؟ در beancount.io ثبت‌نام کنید — دفتر کل شما تنها یک git push فاصله دارد.

پرسش‌های پرتکرار

پرسش‌های پرتکرار مشتریان

MCP چیست و چرا برای Beancount اهمیت دارد؟

MCP (Model Context Protocol) یک استاندارد باز است که به دستیارهای هوش مصنوعی امکان می‌دهد ابزارها و منابع داده‌ی بیرونی را به شیوه‌ای ساختاریافته و ایمن فراخوانی کنند. آن را همچون یک درگاه USB برای هوش مصنوعی در نظر بگیرید: به‌جای آنکه هوش مصنوعی حدس بزند یا از شما بخواهد داده را بچسبانید، مستقیماً به سامانه‌های شما متصل می‌شود. برای کاربران Beancount، این یعنی کلاینت هوش مصنوعی شما می‌تواند داده‌های واقعی دفتر کل شما را پرس‌وجو کند، فایل‌های واقعی شما را بخواند و ویرایش‌های دقیق انجام دهد — نه اینکه درباره‌ی محتوای احتمالی آن‌ها حدس بزند.

کدام کلاینت‌های هوش مصنوعی با سرور Beancount MCP کار می‌کنند؟

هر کلاینت سازگار با MCP که از OAuth 2.1 پشتیبانی می‌کند بی‌درنگ کار می‌کند. سرور Beancount MCP جریان کامل اجازه‌دهی OAuth 2.1 را با PKCE پیاده‌سازی می‌کند، بنابراین کلاینت‌هایی مانند Claude Code به‌طور خودکار نقطه‌ی پایانی اجازه‌دهی سرور را کشف می‌کنند و از شما می‌خواهند وارد شوید — بدون نیاز به کپی دستی توکن یا پیکربندی. پس از آنکه دسترسی را تأیید کردید، کلاینت اعتبارنامه‌ها را به‌طور خودکار ذخیره و تازه می‌کند.

کلاینت‌هایی با پشتیبانی شناخته‌شده‌ی MCP + OAuth 2.1 شامل Claude Code CLI، Claude Desktop، Cursor، Windsurf و Zed می‌شوند. با رشد بوم‌سازگان MCP، هر کلاینت جدیدی که از مشخصات OAuth 2.1 MCP پیروی کند بدون تغییری از سمت ما کار خواهد کرد.

چگونه دفتر کل خود را متصل کنم؟

برای کلاینت‌هایی که از OAuth 2.1 پشتیبانی می‌کنند (مانند Claude Code):

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

برای کلاینت‌های بدون پشتیبانی OAuth 2.1، یک توکن ایستا (محدود به یک دفتر کل) از تنظیمات حساب Web Beancount خود بسازید و آن را به‌عنوان یک هدر Authorization: Bearer ارسال کنید.

آیا این همان قابلیت گفت‌وگوی «Ask AI» در داشبورد است؟

آن‌ها ابزارهای زیربنایی یکسان دفتر کل را به اشتراک می‌گذارند (پرس‌وجوهای BQL، خواندن/نوشتن فایل)، اما سرور MCP یک نقطه‌ی ورود متفاوت است. قابلیت Ask AI داشبورد یک تجربه‌ی گفت‌وگوی میزبانی‌شده با یک محیط ایزوله‌ی Claude Code مبتنی بر Cloudflare است. سرور MCP یک نقطه‌ی پایانی پروتکل است که از کلاینت هوش مصنوعی دلخواه خودتان به آن متصل می‌شوید — که به شما کنترل بیشتر، مدل‌های بیشتر و یکپارچگی عمیق‌تر با جریان کاری موجودتان می‌دهد.

هوش مصنوعی واقعاً با دفتر کل من چه کاری می‌تواند انجام دهد؟

سرور MCP چهار ابزار را در دسترس قرار می‌دهد:

ابزار	کارکرد آن
`runBqlQuery`	اجرای BQL (زبان پرس‌وجوی Beancount) برای پرس‌وجوی مانده‌ها، تراکنش‌ها، حساب‌ها
`listLedgerFiles`	مرور ساختار پوشه‌های مخزن دفتر کل شما
`readLedgerFiles`	خواندن محتوای فایل‌های `.beancount` و دیگر اسناد دفتر کل
`editLedgerFiles`	ایجاد، به‌روزرسانی، جایگزینی یا حذف فایل‌ها در یک commit اتمیک git

هوش مصنوعی می‌تواند این‌ها را ترکیب کند: ساختار فایل شما را کشف کند، فایل‌های مرتبط را برای زمینه بخواند، یک پرس‌وجوی BQL برای پاسخ به پرسش شما بنویسد، یا یک ویرایش را پیشنهاد و ثبت کند.

آیا هوش مصنوعی می‌تواند دفتر کل من را بدون اطلاع من تغییر دهد؟

ویرایش فایل‌ها مستلزم آن است که کلاینت هوش مصنوعی editLedgerFiles را همراه با توصیفی از آنچه تغییر می‌دهد فراخوانی کند. کلاینت‌های خوش‌رفتار MCP (از جمله Claude Code) این را پیش از اجرا به شما نشان می‌دهند. ویرایش‌ها همچنین از یک حالت dry_run پشتیبانی می‌کنند که تغییرات دقیق را بدون نوشتن هیچ‌چیز پیش‌نمایش می‌دهد، بنابراین کلاینت شما می‌تواند ابتدا یک diff به شما نشان دهد. و هر تغییر ثبت‌شده یک commit واقعی git در مخزن دفتر کل شماست، بنابراین یک ردپای حسابرسی کامل دارید و می‌توانید هر چیزی را با ابزارهای استاندارد git بازگردانید.

آیا داده‌های من به شخص ثالث ارسال می‌شود؟

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

هر توکن محدود به دفتر کل است — این یعنی چه؟

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

آیا سرور MCP نیازمند در حال اجرا بودن رابط وب Fava است؟

خیر. سرور MCP با API داخلی Fava که توسط زیرساخت Web Beancount مدیریت می‌شود گفت‌وگو می‌کند (Fava رابط وبی است که دفتر کل beancount.io شما را نیرو می‌دهد). لازم نیست رابط Fava باز یا در دسترس باشد.

اگر دسترسی MCP خود را لغو کنم چه اتفاقی می‌افتد؟

نشست‌های جاری MCP در فراخوانی ابزار بعدی خطاهای 401 دریافت می‌کنند. کلاینت‌هایی که از OAuth 2.1 پشتیبانی می‌کنند به‌طور خودکار برای اجازه‌دهی مجدد تلاش می‌کنند و از شما می‌خواهند دوباره وارد شوید.

زیر کاپوت

برای کنجکاوان فنی — اینکه سرور چگونه ساخته شده است.

چرا MCP به‌جای ساختن API/افزونه‌ی اختصاصی خودمان برای هر ابزار هوش مصنوعی؟

MCP استاندارد نوظهور است و پیش‌تر توسط همه‌ی ویرایشگرهای بزرگ هوش مصنوعی پشتیبانی می‌شود. ساختن یک سرور MCP سازگار، سازگاری با کل بوم‌سازگان را یک‌جا به ما می‌دهد، در برابر نگهداری یکپارچه‌سازی‌های جداگانه برای Claude، Cursor، Windsurf و هر چه سه‌ماهه‌ی بعد عرضه شود. پروتکل، کشف، طرح‌واره‌های ابزار و جریان‌سازی را مدیریت می‌کند — ما بر منطق حوزه تمرکز می‌کنیم.

چرا OAuth 2.1 به‌جای کلیدهای API ایستا؟

OAuth 2.1 با PKCE همان چیزی است که مشخصات MCP برای سرورهای راه‌دور توصیه می‌کند، و همان است که کلاینت‌هایی مانند Claude Code به‌طور بومی پیاده‌سازی می‌کنند. فایده‌ی عملی: کاربران هرگز به یک توکن دست نمی‌زنند. کلاینت سرور اجازه‌دهی را از طریق نقطه‌ی پایانی فراداده‌ی .well-known/oauth-protected-resource ما کشف می‌کند، PKCE را تکمیل می‌کند و تازه‌سازی را به‌طور خودکار مدیریت می‌کند. توکن‌های ایستا همچنان به‌عنوان یک جایگزین برای کلاینت‌هایی که جریان کامل را پیاده‌سازی نکرده‌اند پشتیبانی می‌شوند.

چرا Streamable HTTP به‌جای انتقال SSE یا stdio؟

Streamable HTTP انتقال MCP است که برای سرورهای راه‌دور روی HTTPS طراحی شده است. stdio برای فرآیندهای محلی است. SSE (انتقال قدیمی‌تر MCP) به نفع Streamable HTTP در حال منسوخ‌شدن است. کاربران ما از کلاینت‌های هوش مصنوعی‌ای متصل می‌شوند که هم‌مکان با سرور ما نیستند، بنابراین Streamable HTTP انتخاب درست و آینده‌نگر است.

چرا نشست MCP بدون حالت است (بدون sessionIdGenerator)؟

ما sessionIdGenerator: undefined را تنظیم می‌کنیم تا هر درخواست کاملاً بدون حالت باشد — هیچ حالت نشست سمت سروری میان فراخوانی‌های ابزار تخصیص یا نگه‌داشته نمی‌شود. این با حالت بدون‌حالتِ مشخصات Streamable HTTP هم‌خوانی دارد و سرور را بدون وابستگی نشست به‌صورت افقی مقیاس‌پذیر نگه می‌دارد. زمینه‌ی ابزار (هویت دفتر کل، کلاینت API Fava) در هر درخواست از توکن معتبرشده‌ی OIDC بازسازی می‌شود.

تأیید دسترسی دفتر کل چگونه کار می‌کند؟

پس از اعتبارسنجی توکن OIDC، resolveLedgerAccess از طریق API Fava بررسی می‌کند که کاربر احرازهویت‌شده واقعاً به دفتر کل درخواست‌شده دسترسی دارد. این مانع از آن می‌شود که یک توکن معتبر برای یک دفتر کل برای کاوش دفتر کل کاربری دیگر استفاده شود (دفاع لایه‌لایه روی توکن امضاشده).

editLedgerFiles به کجا ثبت می‌کند؟

این changeLedgerFiles را روی API Fava فراخوانی می‌کند، که یک commit git در مخزن Gitea دفتر کل با پیام AI edit: <description> ایجاد می‌کند. توصیف از فیلد description که هوش مصنوعی پر می‌کند می‌آید — که در کلاینت‌های خوش‌رفتار MCP پیش از اجرا به کاربر نشان داده می‌شود.

گزینه‌ی dry_run روی editLedgerFiles چیست؟

dry_run: true همه‌ی عملیات فایل را اعتبارسنجی می‌کند (بررسی می‌کند فایل‌ها وجود دارند، تأیید می‌کند رشته‌های قدیمی str_replace دقیقاً یک‌بار مطابقت دارند) و پیش‌نمایشی از آنچه ثبت می‌شد بازمی‌گرداند — بدون آنکه واقعاً در git بنویسد. این برای کلاینت‌های هوش مصنوعی‌ای که می‌خواهند پیش از ثبت یک diff به کاربر نشان دهند مفید است.

سطح خطای قابل‌مشاهده برای کلاینت‌های هوش مصنوعی چیست؟

خطاهای ابزار به‌صورت { isError: true, content: [{ type: "text", text: "..." }] } بازگردانده می‌شوند — قالب خطای ساختاریافته‌ی MCP SDK. کلاینت هوش مصنوعی پیام خطا را به‌صورت متن دریافت می‌کند و می‌تواند تصمیم بگیرد چگونه با آن برخورد کند (تلاش مجدد، گزارش به کاربر و غیره). خطاهای احرازهویت در سطح HTTP (401) شامل یک هدر WWW-Authenticate هستند که به فراداده‌ی منبع محافظت‌شده‌ی OAuth اشاره می‌کند، بنابراین کلاینت‌های سازگار می‌توانند به‌طور خودکار جریان اجازه‌دهی را از نو آغاز کنند.