Skip to main content
Glama
mf-full-mcp

mf-full-mcp

mf-full-mcp

这是 マネーフォワード クラウド会計 的非官方MCP服务器。在提供与官方beta MCP同名的工具(mfc_ca_*)的同时,追加了以下3点。

  • 凭证的附加 — 上传收据或发票并关联到分录。截至2026年8月,官方远程MCP没有此功能

  • 同时连接多个事业者 — 持有多个法人的令牌,无需重新认证,即可按窗口/会话分别连接到不同的事业者

  • 分录的完全删除 — 官方MCP仅支持创建・更新,不支持删除

设想的是像会计事务所那样,日常在几十家公司的账簿之间来回使用的场景。

这是非官方项目。 与 株式会社マネーフォワード 没有任何关系。不属于该公司的支持范围。


为什么做这个

MF 的访问令牌与在授权画面中选择的一个事业者绑定(证据是 /api/v3/offices 返回的不是数组而是单个对象)。要处理多个法人,就需要持有相应数量的令牌。

官方远程MCP有两个端点,各自情况不同。

官方 beta

官方 alpha

本服务器

同时持有多个法人

不可(切换时需重新认证)

可以

可以

令牌寿命

长时间

约1小时

自动刷新(实测可放置1个月以上)

认证操作

自动

手动复制粘贴认证码

自动

凭证附加

不可

不可

可以

beta版认证方便,但只能持有1个事业者;alpha版虽然能持有多个,但令牌约1小时就会过期,需要手动重新认证。

**“无需被重新认证打扰、按窗口分别操作多个法人”这一状态,官方两个版本都无法实现。**本服务器通过自备OAuth填补了这一缺口。


Related MCP server: MF Invoice MCP

设计要点

1. 自备OAuth(动态客户端注册)

通过RFC 7591动态客户端注册,在每次认证时注册公共客户端(token_endpoint_auth_method: "none" + PKCE)。

因此无需事先注册应用,client_secret 本身就不存在。无论在这个仓库中,还是在用户环境中,都不会放置任何秘密密钥。

2. 按事业者为令牌添加标签并保存

在 ~/.mf-full-mcp/tokens.json(目录0700/文件0600)中,以标签为键保存多个事业者的令牌。思路是:1个令牌=1家公司,需要多少就持有多少即可。

过期时会自动刷新(在到期前60秒提前刷新+遇到401时重试1次)。实测刷新令牌的有效期超过1个月,只要认证一次就可以放置较长时间。

3. 活动事业者按“会话”独立

这是本项目的核心。

use_office 切换的只是进程内的内存,不会重写共享文件中的 active。共享文件中的值仅作为尚未进行任何切换的新进程的初始值被读取。

结果是,可以在窗口A操作甲公司、窗口B操作乙公司,并行进行。

如果在这里重写共享文件,那么一方切换事业者的瞬间,另一方就会获取到其他法人的数据。既然处理的是账簿,这是绝不允许发生的事故。“多公司同时连接”的实质,与其说是能持有多个令牌,不如说在于不共享活动状态。

如果想在启动时固定,请使用环境变量 MF_FULL_OFFICE。

4. 回调端口自动分配

通过 server.listen(0) 让操作系统分配空闲端口,在确定的端口上组装好 redirect_uri 之后再进行客户端注册(RFC 8252 的 loopback redirect)。

如果是固定端口,在第二个窗口中的认证会因 EADDRINUSE 而失败。“listen → 确定端口 → register → authorize”这一顺序,正是为了让第3点的设计实际发挥作用所必需的。

为了向后兼容,仅当显式指定 MF_FULL_CALLBACK_PORT 时才使用固定端口。


凭证的附加

官方远程MCP所提供的工具,截至2026年8月只到分录・报表・明细・主数据的操作,不包含处理凭证(收据・发票)的工具。要将凭证关联到分录,只能通过浏览器手动操作。

本服务器将其作为工具提供。只需传入本地文件的绝对路径,即可完成从 base64 编码、上传到附加到分录的全部操作。

mfc_ca_postVouchers(journal_id: "<仕訳ID>", file_paths: ["/path/to/receipt.pdf"])

如果要解除关联,请使用 mfc_ca_deleteVouchers。

从“创建分录,再附加对应的收据”能够在同一个流程中完成,是制作本服务器的动机之一。

注意 — 如果省略 journal_id,凭证将成为不关联任何分录的孤立凭证,之后没有任何手段再关联到分录。原则上请务必指定。


环境要求

  • Node.js 20 及以上

  • マネーフォワード クラウド会計 的账户

安装

git clone https://github.com/kentaroajisaka/mf-full-mcp.git
cd mf-full-mcp
npm install
npm run build

注册到 MCP 客户端(Claude Code 的情况下为 ~/.claude.json)。

{
  "mcpServers": {
    "mf-full": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mf-full-mcp/dist/index.js"],
      "env": {}
    }
  }
}

使用方法

认证第1家公司

authenticate(label: "company-a")

在浏览器中打开返回的 authUrl,选择事业者并授权。完成后用 auth_status 确认。

添加第2家及以后的公司

只需用不同的标签重复同样的步骤即可。

authenticate(label: "company-b")

切换连接目标

list_offices          保存済み事業者の一覧
use_office            このセッションの接続先を切り替える
mfc_ca_currentOffice  いまどの事業者に繋がっているか確認する

use_office 不会影响其他会话。建议在获取数据前,用 mfc_ca_currentOffice 确认目标法人的做法。

工具列表

认证・事业者管理

工具

说明

authenticate

开始 OAuth 认证(可通过 extra_scopes 请求工资等附加作用域)

auth_status

确认进行中的认证流程状态

list_offices

显示已保存的事业者和当前连接目标

use_office

切换本会话的连接目标

remove_office

删除已保存的令牌

mf_full_info

显示请求作用域・回调端口等设置

官方MCP兼容(mfc_ca_*)

事业者・会计期间、会计科目、辅助科目、部门、税种区分、往来单位、联动服务、分录的获取/创建/更新、试算表(BS・PL)、推移表(BS・PL)、明细的获取/创建/分录化。

官方MCP未提供的功能

工具

说明

mfc_ca_postVouchers

上传凭证并附加到分录(传入本地文件路径后自动进行 base64 编码)

mfc_ca_deleteVouchers

解除分录与凭证的关联(凭证本身会作为孤立凭证保留)

mfc_ca_deleteJournals

完全删除分录

环境变量

变量

默认值

说明

MF_FULL_OFFICE

无

启动时将会话的连接目标事业者固定

MF_FULL_CALLBACK_PORT

自动分配

固定 OAuth 回调端口

MF_FULL_SCOPES

会计16个作用域

覆盖请求的作用域

MF_FULL_CLIENT_NAME

mf-full-mcp

动态客户端注册时的客户端名称


已知注意事项

MF 的 API 有几个容易踩的坑。

  • ID 的编码 — MF 的 ID 源自 Base64,包含 %2F 等字符。在嵌入 URL 路径时如果不重新编码,路径会被破坏并返回 403。本服务器已采取应对措施,但返回的 ID 请原样传递,不要加工。

  • putJournals 是全量替换 — 不支持部分更新。更新前请保留原始分录。

  • 写操作类工具的使用 — 分录的创建・更新、凭证的附加・解除、明细的分录化会改写账簿。从 AI 代理使用时,请务必在执行前加入人工审批的做法。

安全

令牌存放在哪里

官方远程MCP的认证在服务器侧完成。授权和令牌交换以MCP工具的形式提供,用户没有直接处理 access_token 的场景。也就是说,MF 的令牌不会存放在用户的终端上。

本服务器则相反,令牌存放在自己的终端上。它以明文保存在 ~/.mf-full-mcp/tokens.json 中(目录 0700 / 文件 0600)。

这是一种权衡。之所以能够无需重新认证地持有多个法人,也能够在到期后自动更新并放置较长时间,正是因为刷新令牌就在手边。反过来,如果这个文件泄露,保存的所有事业者的账簿都会被访问。

在此基础上,前提是采取以下做法:

  • 要在磁盘已加密的个人终端上使用。不要在共用终端上使用

  • 不再需要的事业者要用 remove_office 删除

  • 保存到操作系统钥匙串是今后的课题

client_secret 不存在

通过动态客户端注册,设计为无需保管秘密密钥。这个仓库和用户环境中都不会放置 client_secret。

免责声明

本软件为非官方软件,与 株式会社マネーフォワード 没有任何关系。

本服务器要求的部分作用域,**可能会因MF侧的规格变更而在未预告的情况下无法使用。**此时,凭证相关等功能会无法运行。

鉴于会计账簿这一性质,使用请注意以下几点:

  • 对于写入操作的结果,作者不承担任何责任

  • 在用于正式账簿之前,请先通过测试事业者确认运行情况

  • 使用时请各自确认 マネーフォワード 的使用条款

以 MIT 许可证提供。详情请参阅 LICENSE。

相关

Available Tools

29 tools
authenticateA

MFへのOAuth認証を開始する。返ってきたauthUrlをユーザーがブラウザで開き、事業者を選択して許可すると自動でトークンが保存される。完了確認はauth_status。

Inputs: label, extra_scopes.

auth_statusA

進行中の認証フローの状態を確認する(waiting/exchanging/done/error)。

Inputs: no named parameters.

list_officesA

保存済みトークン(事業者)の一覧とアクティブな接続先を表示する。

Inputs: no named parameters.

mfc_ca_currentOfficeB

事業者情報と会計期間を取得します。

Inputs: no named parameters.

mfc_ca_deleteJournalsA

仕訳を完全削除します(公式MCP未提供・帳簿書き込み。要ユーザー承認)。

Inputs: id (required).

mfc_ca_deleteVouchersA

仕訳と証憑の紐付けを解除します(証憑自体は孤立して残る。公式MCP未提供・要ユーザー承認)。

Inputs: journal_id (required), voucher_file_id (required).

mfc_ca_getAccountsC

勘定科目を取得します。

Inputs: available.

mfc_ca_getConnectedAccountsB

連携サービス(自動連携・手動管理とも)を取得します。

Inputs: no named parameters.

mfc_ca_getDepartmentsB

部門を取得します。

Inputs: available.

mfc_ca_getJournalByIdB

仕訳を1件取得します。

Inputs: id (required).

mfc_ca_getJournalsB

仕訳一覧を取得します。start_date または end_date のいずれかが必要。

Inputs: page, end_date, per_page, account_id, +3 more.

mfc_ca_getReportsTransitionBalanceSheetB

貸借対照表の推移表(月別)を取得します。

Inputs: type (required), end_month, fiscal_year, include_tax, +2 more.

mfc_ca_getReportsTransitionProfitLossC

損益計算書の推移表(月別)を取得します。

Inputs: type (required), end_month, fiscal_year, include_tax, +2 more.

mfc_ca_getReportsTrialBalanceBalanceSheetB

貸借対照表の試算表(累計)を取得します。

Inputs: end_date, end_month, start_date, fiscal_year, +4 more.

mfc_ca_getReportsTrialBalanceProfitLossC

損益計算書の試算表(累計)を取得します。

Inputs: end_date, end_month, start_date, fiscal_year, +4 more.

mfc_ca_getSubAccountsC

補助科目を取得します。

Inputs: available.

mfc_ca_getTaxesC

税区分を取得します。

Inputs: available.

mfc_ca_getTermSettingsA

会計年度設定(税込/税抜・課税方式等)を取得します。

Inputs: no named parameters.

mfc_ca_getTradePartnersC

取引先を取得します。

Inputs: available.

mfc_ca_getTransactionsB

連携サービスで収集された明細一覧を取得します(自動連携・手動とも)。

Inputs: end_date (required), start_date (required), page, side, +9 more.

mfc_ca_postJournalsB

仕訳を作成します(帳簿書き込み。要ユーザー承認)。

Inputs: journal (required).

mfc_ca_postTradePartnersB

取引先を作成します。

Inputs: trade_partner (required).

mfc_ca_postTransactionJournalizeA

明細から仕訳を作成します(帳簿書き込み。要ユーザー承認)。相手科目account_idのみ必須。貸借方向・口座側科目・税区分・invoice_kindはMFが自動補完。

Inputs: account_id (required), transaction_id (required), memo, tags, +7 more.

mfc_ca_postTransactionsA

手動管理の連携サービスに明細を作成します(要ユーザー承認)。

Inputs: transactions (required), connected_account_id (required).

mfc_ca_postVouchersA

証憑をアップロードし仕訳に添付します(公式MCP未提供・要ユーザー承認)。file_paths を渡せばローカルファイルを自動でbase64化する。journal_id 省略時は孤立証憑になる(後から仕訳に紐づける手段はない)ので原則指定すること。

Inputs: file_paths, journal_id, voucher_files.

mfc_ca_putJournalsA

仕訳を更新します(全置換API・帳簿書き込み。要ユーザー承認)。

Inputs: id (required), journal (required).

mf_full_infoB

このサーバーの設定情報(要求スコープ・コールバックポート等)を表示する。

Inputs: no named parameters.

remove_officeC

保存済みトークンを削除する。

Inputs: label (required).

use_officeA

このセッションのアクティブな接続先事業者を切り替える(プロセス内メモリのみ。他セッション/他ウィンドウには影響しない)。

Inputs: label (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools have clear resource/action separation: journals, transactions, reports, master data, auth, and office management each have distinct targets. A few pairs like currentOffice vs list_offices or postJournals vs postTransactionJournalize have some boundary overlap, but the descriptions are precise enough to resolve most ambiguity.

    Naming Consistency3/5

    The dominant mfc_ca_get/post/put/delete + Resource pattern is readable and consistent within the core accounting tools. However, the server mixes styles: verbless mfc_ca_currentOffice, un-prefixed snake_case names like remove_office and list_offices, and bare verbs like authenticate.

    Tool Count2/5

    29 tools is a heavy surface and exceeds the 25+ threshold. Although the tools are grouped into clear subdomains such as journals, reports, master data, and auth, the high number of parallel getters and report variants creates meaningful selection overhead for agents.

    Completeness3/5

    Core workflows are well covered: authentication, office switching, journal CRUD, report retrieval, and master data reads are all present. Obvious gaps remain, however: trade partners have no update/delete, transactions have no update/delete, and vouchers lack list/get or an attach-orphan recovery path.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      An MCP server and Claude plugin that enables interaction with freee APIs for accounting, human resources, invoicing, and more. It provides secure OAuth 2.0 authentication and integrates detailed API reference skills to support tasks like creating invoices and managing company data through natural language.
      18,608 npm
      521
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that integrates with MoneyForward Cloud Invoice API v3 to automate the creation and management of quotes and invoices. It supports Japanese invoice system compliance, allowing users to handle partners, items, and billing through natural language.
      22
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An unofficial MCP server that integrates with the hokan Insurance CRM API v2 to manage customer data, schedules, and tasks. It also features specialized tools for Japanese insurance law compliance, including intent confirmation and regulatory check generation.
      -