mf-accounting-voucher-mcp

这是一个补充Money Forward 云会计官方MCP服务器未支持功能的本地MCP服务器。它直接调用 REST API v3，与官方MCP（远程）配合使用。

提供的工具

注记: 将合作明细设为「对象外」在 REST API 中不存在，因此不提供此功能。凭证文件的下载同样API不支持。官方MCP已提供的功能（如 getJournals 等）不会重新实现。

凭证文件的二进制数据不经过LLM。该服务器（Node进程）接收本地文件路径，读取并转换为base64后发送到API。

Related MCP server: freee-chat-mcp-server

设置

1. 在应用门户注册应用

在Money Forward的应用门户创建应用，并进行以下设置。

• 重定向URI: http://127.0.0.1:53682/callback

• 作用域:

  • mfc/accounting/voucher.write（凭证的注册、删除）

  • mfc/accounting/journal.write（分录的注册、更新、删除）

记录下发行的 客户端ID / 客户端密钥。

2. 安装与构建

pnpm install && pnpm run build

3. 环境变量的设置

export MF_CLIENT_ID="（クライアントID）"
export MF_CLIENT_SECRET="（クライアントシークレット）"

4. 首次授权

pnpm run auth

浏览器会打开，请登录Money Forward并进行授权。令牌将保存到 ~/.mf-accounting-voucher-mcp/tokens.json（mode 600），之后会自动刷新。

注册到 Claude Desktop / Cowork

注册一次后，MCP服务器会在客户端启动时自动启动。无需日常手动启动操作。

推荐：使用钥匙串（不将密钥写入配置文件）

仅在首次将认证信息注册到macOS钥匙串：

security add-generic-password -s mf-accounting-voucher-mcp -a client_id -w '（クライアントID）' -U
security add-generic-password -s mf-accounting-voucher-mcp -a client_secret -w '（クライアントシークレット）' -U

在 claude_desktop_config.json 的 mcpServers 中注册启动脚本（请将路径替换为实际安装位置）：

{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "/path/to/mf-accounting-voucher-mcp/scripts/mf-accounting-voucher-mcp.sh",
      "args": []
    }
  }
}

首次OAuth授权也可以通过脚本执行（无需设置环境变量）：

scripts/mf-accounting-voucher-mcp.sh auth

替代方案：将环境变量直接写入配置文件

{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "node",
      "args": ["/path/to/mf-accounting-voucher-mcp/dist/index.js"],
      "env": {
        "MF_CLIENT_ID": "（クライアントID）",
        "MF_CLIENT_SECRET": "（クライアントシークレット）"
      }
    }
  }
}

请注意此方法会将密钥以明文形式保留在配置文件中。

使用示例

「この領収書（/Users/xxx/Downloads/receipt.pdf）を仕訳 XXXX に添付して」
→ post_vouchers が呼ばれ、添付結果（voucher_file_ids）が返る

「仕訳 XXXX の証憑 a60cd25d-... の添付を解除して」
→ delete_voucher

「仕訳 XXXX を削除して」
→ delete_journal（実行前に仕訳内容の提示と明示的な確認が入る）

可以通过官方MCP的 getJournalById 获取目标分录，并确认 voucher_file_ids 中已反映来验证附加结果。

注意事项

• MF的文件类型・大小・数量的准确限制请参考官方规范 /specs/vouchers（本服务器的上限是本地侧的安全阀）

• 切换事业者（办公室） 通过重新执行 pnpm run auth 进行

• delete_journal 无法撤销。调用方（LLM）的设计是在取得用户明确确认后才执行