FreeAgent MCP

[!WARNING] Этот проект на 100% написан вайб-кодом. Я не проверял всё и не смотрел код. Что-то может работать. Используйте на свой страх и риск.

Локальный, только для чтения MCP-сервер, который отдаёт бухгалтерские данные FreeAgent AI-клиентам (Claude Desktop, настольному приложению ChatGPT и любому другому, кто умеет работать с MCP через stdio). Он позволяет спрашивать что-то вроде «почему на номинальном коде 907 стоит £4,200?» — и модель сама проваливается в лежащие под этим транзакции.

Режим только для чтения обеспечивается на уровне HTTP-клиента: клиент предоставляет метод get() и ничего больше — любая попытка вызвать другой глагол вызывает исключение. Каждый инструмент размечен как read-only и идемпотентный. В коде нет пути, который мог бы изменить бухгалтерские данные, а эндпоинты отправки VAT filing / MTD не трогаются вовсе.

Сервер построен на Laravel, поэтому если у вас не настроен локальный PHP (например, через Herd) — возможно, он окажется не особенно полезен. Хотя можно использовать, например, Laravel Sail и запустить его в Docker-контейнере вместо этого.

Настройка

1. Установите зависимости и выполните миграции:

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

2. Зарегистрируйте OAuth-приложение в FreeAgent Developer Dashboard, указав http://localhost в качестве redirect URI — FreeAgent принимает только те redirect URI, которые точно совпадают с зарегистрированным для приложения. Потом добавьте ключи в .env:

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

   Если для вашего приложения уже зарегистрирован другой redirect 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 (Настройки → Разработчик → Изменить конфигурацию):

{
    "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 (или через Настройки → MCP-серверы → Добавить сервер → 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 автоматически одобряет read-only инструменты и запрашивает подтверждение для всего остального — поскольку каждый инструмент здесь помечен как read-only, это означает никаких запросов и жёсткую подстраховку. Обратите внимание: это работает только в настольном приложении 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