freeagent-mcp-remote

这个“连接器”是为了让 Claude 能访问我的 FreeAgent 数据而构建的。目前它是一个内部工具，但我尽量写得清楚易懂，面向普通公众，以防对其他人也有用。如果你在安装、适配方面需要帮助，或者想为你的业务定制类似的工具，来提问。

灵感来自 samaxbytez/freeagent-mcp 虽然最初我打算在其基础上进行开发，但我最终决定从零开始，使用 [https://gofastmcp.com] 和 Python。

• WIP — “work in progress”（“进行中”）。这是开发人员使用的术语，在本文档中用于标记尚不可用的功能，相当于“即将推出”。

现有功能

两者共用相同的设置，因此按照下面的步骤操作，今天就能得到可用的那一半。

工作原理

这个项目是一个小型服务器，位于 FreeAgent 和 Claude（或其他 AI 提供商）之间，充当翻译器。连接后，你可以向 Claude 提问，比如 “三月份还有哪些银行交易未解释？”，然后 Claude 就会去查看。

这种翻译器的技术名称是 MCP 服务器——MCP 是用于将 AI 助手连接到外部工具的共享标准。在 Claude 中，它们以连接器的形式出现。使用它时，你不需要了解更多。

补充阅读：

什么是 MCP？ 用通俗的语言解释（可以想象成“AI 的 USB-C 接口”）。

自定义连接器入门。

设置

命令行工具和（将来的）连接器都需要此设置。本文假设你能使用终端，但不一定以前构建过 Python 服务。

1. 获取 FreeAgent 凭据

在连接 FreeAgent 之前，你需要注册一个“应用”。这会给你两个字符串——客户端 ID 和客户端密钥——它们共同向 FreeAgent 标识此服务器。这样，同一个“应用”可以安装到不同的 FreeAgent 组织；例如，如果某个“应用”被发现是恶意的，FreeAgent 可以立即从所有组织中卸载它。遗憾的是，即使你只想连接自己的账户，也必须进行此注册。

1. 前往 FreeAgent 开发者仪表板 并登录。

2. 创建一个应用。

3. 将 OAuth 重定向 URI 设置为 http://localhost:8723/callback。这是你批准访问后 FreeAgent 将浏览器重定向回的位置，因此必须完全匹配——末尾的斜杠会导致失败。

   该地址是命令行工具使用的地址，因为浏览器会返回到你自己的机器。连接器一旦部署，将通过公共 Web 地址访问，因此需要注册自己的重定向 URI——<the container's URL>/auth/callback。现在无需对此做任何操作；部署运行手册 会在关键时点进行说明。了解这一点只是为了让你以后看到两个不同的地址时，不会觉得其中一个是错误的。

4. 如果还没有，请将 .env.example 复制为 .env。该文件不会提交到 git，这要感谢 .gitignore。将 OAuth 标识符和密钥作为 FREEAGENT_CLIENT_ID 和 FREEAGENT_CLIENT_SECRET 复制到其中。

2. 安装

你首先需要安装的唯一工具是 uv，它是一个管理 Python 项目的工具。它会为你获取合适的 Python 版本，因此你不需要预先安装 Python，也不需要了解任何关于虚拟环境的知识。

在 Mac 上，使用 Homebrew：

brew install uv
uv --version    # check it worked

其他平台和其他安装方式，请参阅 uv 安装指南。

然后：

git clone <this-repo> && cd freeagent-mcp-remote
uv sync                 # creates .venv, installs everything, fetches Python 3.14
cp .env.example .env    # then add the credentials from the step above

uv sync 第一次需要一分钟，之后几乎瞬间完成。

uv run <command> 会在该环境中运行命令，这就是下面每条命令都以它开头的原因。

3. 授权

uv run scripts/fa_auth.py

浏览器会打开，你批准访问后，它会将一个令牌写回 .env。FreeAgent 的访问令牌有效期为一小时，但刷新令牌会同时保存并自动使用，所以这确实是一次性步骤。

沙盒。 FreeAgent 在 signup.sandbox.freeagent.com 提供一个免费的沙盒——一个可以安全写入的临时公司。它需要自己的注册和自己的应用注册；沙盒凭据不能用于生产环境。通过设置 FREEAGENT_API_BASE_URL=https://api.sandbox.freeagent.com/v2 来指向它，登录端点会自动跟随，因此两者不会混淆。在写入任何内容之前值得先做；对于读取则不必，因为沙盒中没有你的真实数据。

使用命令行工具

目前可用。它可以从终端读取你 FreeAgent 账户的任何部分，并为你处理登录。

FreeAgent 的数据按“端点”组织——/company、/invoices、/bank_accounts 等。FreeAgent API 文档 列出了全部端点。你可以像这样请求一个：

uv run fastmcp call scripts/freeagent_api_caller.py request path=/company

一些可以尝试的示例

以下操作都是只读且安全的。

# Your company profile: year end dates, VAT registration, company type
uv run fastmcp call scripts/freeagent_api_caller.py request path=/company

# Bank accounts, including how many transactions are still unexplained
uv run fastmcp call scripts/freeagent_api_caller.py request path=/bank_accounts

# Trial balance — every nominal account and its total
uv run fastmcp call scripts/freeagent_api_caller.py request \
    path=/accounting/trial_balance/summary

# One contact, to see what fields a contact has
uv run fastmcp call scripts/freeagent_api_caller.py request \
    --input-json '{"path": "/contacts", "params": {"per_page": "1"}}'

# Click around in a browser instead
uv run fastmcp dev inspector scripts/freeagent_api_caller.py

简单参数以 key=value 形式传递。嵌套参数——params 和 body——需要 --input-json，它可以携带整个调用。

控制输出规模

列表端点可能返回数千条记录。有两种方法可以修剪，它们可以组合使用：

• per_page=1 限制返回的记录数量。这通常是你想要的——一条真实记录会显示值的实际格式。

• shape_only=true 仅显示字段名和类型，不显示值。在开发过程中学习 API 结构时很有用。

uv run fastmcp call scripts/freeagent_api_caller.py request path=/invoices shape_only=true

其他选项

更改数据（POST、PUT、DELETE）需要 confirm_write=true。这是有意设置的障碍——这些是你的真实会计记录。这类操作请使用沙盒。

[WIP] Claude 连接器

尚未准备好。等它准备好后，你可以将其作为连接器添加到 Claude，然后用自然语言提问，而不是自己调用端点：

• 处理未解释的银行交易，并建议如何分类

• 调出某个期间的损益表、资产负债表或试算平衡表

• 查看日记账分录，或过账更正

• 为增值税申报和公司税准备数据

• 审查工资和 PAYE 数据

• 根据你的实际利润，考虑工资与股息之间的分配

• 跟踪时间、任务和项目

与命令行工具的区别在于，连接器将上述每一项都作为独立、细粒度的能力暴露出来，而不是一个通用的“调用一切”命令——原因见下文安全部分。

面向开发人员

日常命令

uv run pytest                  # run the tests
uv run pytest --lf             # just the ones that failed last time
uv run ruff format .           # auto-format the code
uv run ruff check .            # find likely mistakes and style problems
uv run mypy                    # check the types line up

mypy 是唯一值得不跳过的：它设置为严格模式，因此能在这类“这里可能什么都没有”的错误运行之前发现它们。

提交时的检查

git 钩子 会在你每次提交时自动运行全部四项检查。只需启用一次：

git config core.hooksPath .githooks

整套检查大约需要两秒钟。如果有检查失败，提交会停止，你会看到输出。

如果仍然要提交，请使用 git 内置的绕过方式：

git commit --no-verify -m "..."

该钩子还会直接拒绝提交 .env，因为其中包含有效的 FreeAgent 密钥和访问令牌。

开发连接器

# What tools does the server expose, and what do their inputs look like?
uv run fastmcp inspect src/server.py:create_server

# Click through it in a browser
uv run fastmcp dev inspector src/server.py:create_server

注意末尾的 :create_server——这些命令需要文件以及其中构建服务器的函数名，而不仅仅是文件名。

FreeAgent 的文档存在缺口、矛盾之处，以及至少两个复制粘贴错误，因此连接器的工具是根据真实的 API 响应设计的，而不是根据文档。这正是上面命令行工具的用途。scripts/freeagent_api_caller.py 仅限本地使用，绝不能部署；如果它出现在部署的服务器上，会有一个测试失败。

学习

缓存

运行工具后会出现三个目录。它们都是生成的、被 git 忽略的，并且永远不会作为程序的输入——删除其中任何一个都不会有损失，只是下一次运行会变慢。

• .mypy_cache/ —— mypy 对每个文件类型的学习结果，因此重新检查未更改的文件只是读取缓存，而不是重新分析。这是最重要的一个：没有它，每次运行都会重新分析所有依赖的类型信息。

• .pytest_cache/ —— 上次哪些测试失败了。这是 pytest --lf（上次失败）和 --ff（先失败）功能的支撑，因此你可以只针对失败的测试进行迭代。

• .ruff_cache/ —— 每个文件的 lint 结果。Ruff 足够快，你几乎不会注意到少了它。

如果出现任何异常行为，rm -rf .mypy_cache .pytest_cache .ruff_cache 是一种安全的重置方式。

如果遇到问题

我为自己公司的账簿构建了这个工具，并认真写好了文档，以防对其他人有用。

如果你正在尝试设置类似的东西但进展不顺利，我专业从事这类工作，很乐意聊聊。

如果你发现了 bug 或这里有什么不对，欢迎提 issue。