FreeAgent MCP

[!WARNING] 这个项目 100% 是靠 vibe coding 写出来的。我没有对所有内容做过测试，也没有仔细检查过代码。 功能不一定都能用。使用风险自负。

这是一个本地、只读的 MCP 服务器，将 FreeAgent 的会计数据暴露给 AI 客户端（Claude Desktop、ChatGPT 桌面应用，或其他任何通过 stdio 支持 MCP 的客户端），因此你可以提出类似 "为什么科目代码 907 里有 £4,200？" 的问题，并让模型进一步查看底层交易。

只读约束在 HTTP 客户端层就得到执行：客户端只暴露了一个 get() 方法，没有其他任何内容——任何尝试调用其他动词的行为都会抛出异常。每个工具都被标记为只读且幂等。不存在能修改会计数据的代码路径，VAT 申报 / MTD 提交端点也完全不会被碰触。

该服务器基于 Laravel 构建，所以如果你本地没有配置 PHP 环境（使用 Herd 或类似工具），它可能对你没什么用处。不过，你也可以用 Laravel Sail 将它在 Docker 容器中运行。

设置

1. 安装并迁移：

   composer install
   cp .env.example .env
   php artisan key:generate
   php artisan migrate

2. 在 FreeAgent Developer Dashboard 上注册一个 OAuth 应用，并将 http://localhost 设置为重定向 URI——FreeAgent 只接受与应用中已注册的 URI 完全一致的重定向 URI。然后把密钥添加到 .env：

   FREEAGENT_CLIENT_ID=your-client-id
   FREEAGENT_CLIENT_SECRET=your-client-secret
   FREEAGENT_SANDBOX=false

   如果你的应用已经注册了其他重定向 URI，请直接将 FREEAGENT_REDIRECT_URI 设为该值，而不是再注册一个新的。

3. 认证：

   php artisan freeagent:auth

   打开终端打印出的 URL，批准应用，然后把重定向到的 URL 粘贴回终端。令牌会以加密形式存储在 SQLite 中，并从此自动刷新。

4. 验证是否成功：

   php artisan freeagent:status

Related MCP server: freeagent-mcp-server

Claude Desktop

添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
    "mcpServers": {
        "freeagent": {
            "command": "php",
            "args": ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
        }
    }
}

Claude Code

从任意项目添加该服务器（--scope user 会让它在所有项目中可用；去掉该参数则只对当前项目生效）：

claude mcp add freeagent --scope user -- php /absolute/path/to/freeagent-mcp/artisan mcp:start freeagent

或者手动把它添加到某个项目的 .mcp.json 中：

{
    "mcpServers": {
        "freeagent": {
            "command": "php",
            "args": ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
        }
    }
}

在会话内输入 /mcp 检查它是否已连接。

ChatGPT 桌面应用

添加到 ~/.codex/config.toml（或通过 Settings → MCP servers → Add server → STDIO）：

[mcp_servers.freeagent]
command = "php"
args = ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
cwd = "/absolute/path/to/freeagent-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

writes 模式会自动批准只读工具，并对其他所有操作给出提示。由于这里每个工具都被标记为只读，这意味着不会出现任何提示，并带有一道硬性兜底。请注意：这仅适用于 ChatGPT 桌面应用；ChatGPT 网页版看不到它。

工具

其他命令

php artisan freeagent:status       # auth state + connected company
php artisan freeagent:clear-cache  # drop cached API responses
php artisan mcp:inspector freeagent # debug the server interactively

响应会缓存在数据库中（报表和参考数据缓存 1 小时，交易数据缓存 15 分钟），因此重启 MCP 客户端不会耗尽 FreeAgent 的速率限制（120 次请求/分钟，3,600 次/小时）。