FreeAgent MCP

[!WARNING] このプロジェクトは100%バイブコーディングです。私はすべてをテストしたわけでも、コードを精査したわけでもありません。 動作しないことがあるかもしれません。使用は自己責任でお願いします。

ローカルで動作し、FreeAgentの会計データをAIクライアント（Claude Desktop、ChatGPTデスクトップアプリ、stdioでMCPを話すその他のクライアント）に公開する、読み取り専用の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アプリを登録し、リダイレクトURIにhttp://localhostを指定します。FreeAgentは、アプリに登録されたリダイレクト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に追加します（設定 → 開発者 → 設定を編集）:

{
    "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モードは読み取り専用ツールを自動承認し、それ以外には確認します。このサーバーのツールがすべて読み取り専用としてマークされているため、確認は発生せず、確実な最終防衛線になります。なお、これはChatGPTデスクトップアプリでのみ動作し、ChatGPT webでは表示されません。

ツール

その他のコマンド

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の利用制限（1分あたり120回、1時間あたり3,600回）を消耗しません。