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

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

![یک لپ‌تاپ سفالی متصل به یک دفتر کل سبز باز، با یک رسید در سینی بررسی و بلوک‌های پیوندی که تاریخچه Git را نشان می‌دهند.](/img/blog/beancount-mcp/hero.webp)

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

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

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

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

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

### Claude Code

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

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

Claude Code را باز کنید، `/mcp` را اجرا کنید، `beancount` را انتخاب کنید و جریان احراز هویت آن را دنبال کنید. به Beancount.io وارد شوید و مجوزهای درخواستی را بررسی کنید. برای تأیید اتصال به `/mcp` برگردید. برای جزئیات خاص کلاینت، [دستورالعمل‌های MCP کلود Code](https://code.claude.com/docs/en/mcp) را ببینید.

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

### Claude Desktop و Claude روی وب

**Customize → Connectors** را باز کنید، **Add custom connector** را انتخاب کنید، آدرس سرور را وارد کنید و حساب Beancount.io خود را متصل کنید. اتصال را برای گفتگویی که می‌خواهید از آن استفاده کنید فعال کنید. حساب‌های سازمانی ممکن است ابتدا به یک مالک برای افزودن اتصال نیاز داشته باشند. [راهنمای اتصالات راه دور کلود](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) را دنبال کنید.

### Cursor

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

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

وقتی Cursor آن را درخواست کرد، ورود OAuth را تکمیل کنید، سپس بررسی کنید که ابزارهای سرور در دسترس هستند. [مستندات MCP کرسور](https://cursor.com/docs/mcp) پیکربندی و تنظیمات تأیید ابزار را پوشش می‌دهد.

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

برای کلاینتی که اعتبارنامه‌های Bearer را می‌پذیرد، می‌توانید یک کلید API شخصی در [Settings → Personal access tokens](https://beancount.io/settings/api-keys) ایجاد کنید. **ایجاد کلید به یک پلن پولی 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 فایل را نشان دهید و منتظر تأیید من بمانید.

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

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

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

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

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

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

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

| گردش کار | چه کمکی به شما می‌کند |
| --- | --- |
| `spending-report` | پاسخ به یک سؤال هزینه با BQL پشتیبان و بدون نوشتن در دفتر کل. |
| `reconcile-account` | مقایسه یک حساب با یک صورت ارائه‌شده، طبقه‌بندی تفاوت‌ها و پیشنهاد ورودی‌های از دست رفته. |
| `close-month` | بررسی حساب‌های فعال، ادعاهای تراز، تراکنش‌های دوره‌ای و پرچم‌های حل‌نشده. |
| `categorize-imports` | بررسی تراکنش‌های بانکی مرحله‌بندی‌شده و پیشنهاد دسته‌ها با استفاده از حساب‌های موجود. |

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

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

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

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

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

| مجوز | دسترسی |
| --- | --- |
| `ledger.read` | پرس‌وجو و خواندن داده‌های دفتر کل. |
| `ledger.write` | خواندن داده‌ها و انجام تغییرات معمولی دفتر کل. |
| `ledger.admin` | خواندن، نوشتن و انجام عملیات مدیریتی در صورت مجوز. |

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

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

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

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

## سؤالات رایج

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

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

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

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

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

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

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