freeagent-mcp-remote

この「コネクタ」は、Claude が私の FreeAgent データにアクセスできるようにするために作られました。現時点では社内ツールですが、他の人にも役立つかもしれないので、一般向けにわかりやすく書くように心がけました。セットアップや調整の手助けが必要な場合、あるいはあなたのビジネス向けに同様のツールが必要な場合は、質問する までお問い合わせください。

samaxbytez/freeagent-mcp に触発されました。当初はその上で開発しようと思っていましたが、[https://gofastmcp.com] と Python を使ってゼロから始めることにしました。

• WIP — 「work in progress（作業中）」の略です。開発者が使う用語で、この README 全体でまだ利用できない機能を示すために使われます。「近日公開」に相当します。

利用できるもの

これらは同じセットアップを共有しているので、以下の手順に従えば、今日の時点で動く半分が手に入ります。

仕組み

このプロジェクトは、FreeAgent と Claude（または別の AI プロバイダー）の間に入る小さなサーバーで、変換器の役割を果たします。接続すると、「3月の銀行取引でまだ説明がつかないものはどれ？」 などと Claude に質問でき、Claude が実際に調べに行けるようになります。

この種の変換器の技術的な名称は MCP サーバー です。MCP は AI アシスタントを外部ツールに接続するための共通標準です。Claude ではこれらが コネクタ として表示されます。これ以外に知っておく必要はありません。

参考資料：

MCP とは？ に平易な言葉で説明されています（「AI 用の USB-C ポート」と考えてください）。

カスタムコネクタを始める

セットアップ

コマンドラインツールと（後で追加される）コネクタの両方に必要です。ターミナルの操作ができることを前提に書いていますが、Python サービスを構築した経験は必ずしも必要ありません。

1. FreeAgent の認証情報を取得する

FreeAgent に接続する前に、「アプリ」を登録する必要があります。これにより、クライアント ID と クライアントシークレット という 2 つの文字列が得られます。この 2 つが一緒に、このサーバーを FreeAgent に対して識別させます。こうすることで、1 つの「アプリ」を複数の FreeAgent 組織にインストールできます。たとえば「アプリ」が悪意のあるものと判明した場合、FreeAgent はそれを全組織から一度にアンインストールできます。残念ながら、自分のアカウントにだけ接続したい場合でも、この登録は必須です。

1. FreeAgent Developer Dashboard にアクセスしてサインインします。

2. アプリを作成します。

3. OAuth リダイレクト URI を http://localhost:8723/callback に設定します。ここは、アクセスを承認した後に FreeAgent がブラウザを戻す場所です。そのため、正確に一致する必要があります。末尾のスラッシュがあるだけで機能しません。

   このアドレスはコマンドラインツールが使うものです。ブラウザはあなた自身のマシンに戻ってくるからです。コネクタは、いったんデプロイされると代わりにパブリックな Web アドレスでアクセスされるため、独自のリダイレクト URI を登録する必要があります — <the container's URL>/auth/callback。今のところ何もする必要はありません。デプロイメントランブック が必要になった時点で説明されています。後で 2 つの異なるアドレスを見ても、そのうちの 1 つが間違いだとは思わないようにというだけのことです。

4. まだの場合、.env.example を .env にコピーしてください。このファイルは .gitignore のおかげで git にチェックインされません。OAuth の識別子とシークレットを、FREEAGENT_CLIENT_ID と FREEAGENT_CLIENT_SECRET としてそのファイルにコピーします。

2. インストール

最初にインストールする必要があるのは、Python プロジェクトを管理するツールである uv だけです。uv が適切なバージョンの 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 は最初の1回は1分ほどかかりますが、その後はほぼ瞬時です。

uv run <command> はその環境内でコマンドを実行します。以下のすべてのコマンドがこれで始まるのはそのためです。

3. 認可

uv run scripts/fa_auth.py

ブラウザが開き、アクセスを承認すると、トークンが .env に書き戻されます。FreeAgent のアクセストークンは1時間で失効しますが、リフレッシュトークンが一緒に保存され自動的に使われるため、これは本当に一度だけのステップです。

サンドボックス。 FreeAgent は signup.sandbox.freeagent.com で無料のサンドボックスを提供しています — 安全に書き込みができる使い捨ての会社です。独自のサインアップとアプリ登録が必要です。サンドボックスの認証情報は本番環境では使えません。FREEAGENT_API_BASE_URL=https://api.sandbox.freeagent.com/v2 を設定してサンドボックスを指定すると、ログインエンドポイントも自動的にそれに従うため、2つが交差することはありません。書き込みを行う前にはやっておく価値があります。読み取り専用の場合は、サンドボックスには実際のデータが何もないので、やる価値はありません。

コマンドラインツールを使う

これは今すぐ使えます。ログイン処理を肩代わりし、FreeAgent アカウントの任意の部分をターミナルから読み取ります。

FreeAgent のデータは「エンドポイント」— /company、/invoices、/bank_accounts など — に整理されています。FreeAgent API ドキュメント にすべて記載されています。次のようにして1つをリクエストします：

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 が必要で、これで呼び出し全体を渡せます。

出力を扱いやすく保つ

リストエンドポイントは何千ものレコードを返すことがあります。それを絞り込む方法は2つあり、組み合わせることもできます：

• per_page=1 は返ってくる レコード の数を制限します。通常はこれで十分です。実際の値がどのような形式で入ってくるかを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 に追加し、自分でエンドポイントを呼び出す代わりに、平易な言葉で質問できるようになります：

• 未説明の銀行取引を処理し、カテゴリ分けの方法を提案する

• 期間の損益計算書、貸借対照表、または試算表を表示する

• 仕訳を確認する、または訂正を転記する

• VAT 申告と法人税の数値を準備する

• 給与と 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 はスキップしない価値があります。strict に設定されているため、「ここには何もないかもしれない」という類のバグを、実行される前に捉えてくれます。

コミット時のチェック

git フック が、コミットのたびに4つすべてを自動的に実行します。一度だけ有効にします：

git config core.hooksPath .githooks

スイート全体は約2秒かかります。何かが失敗すると、コミットは停止し、出力が表示されます。

それでもコミットするには、git 組み込みの回避策を使います：

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

フックは、実際の FreeAgent シークレットとアクセストークンを含む .env のコミットも完全に拒否します。

コネクタの開発

# 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 のドキュメントには、欠落、矛盾、そして少なくとも2つのコピーペーストエラーがあります。そのため、コネクタのツールはドキュメントではなく実際の API レスポンスに基づいて設計されています。それが上記のコマンドラインツールの目的です。scripts/freeagent_api_caller.py はローカルのみで、決してデプロイしてはいけません。デプロイされたサーバーにそれが到達すると失敗するテストがあります。

学習

キャッシュ

ツールを一度実行すると、3つのディレクトリが現れます。これらはすべて生成され、gitignore されており、プログラムへの入力になることは決してありません。どれを削除しても、次回の実行が遅くなるだけで、コストはかかりません。

• .mypy_cache/ — mypy が各ファイルの型について学習した内容です。変更されていないファイルを再チェックするときは、新たな分析ではなくキャッシュの読み取りになります。最も重要なものです。これがないと、毎回すべての依存関係の型情報を再分析することになります。

• .pytest_cache/ — 前回失敗したテストが記録されています。これが pytest --lf（最後に失敗したテスト）と --ff（失敗したテストを最初に）を支えており、壊れたテストだけに集中して反復できます。

• .ruff_cache/ — ファイルごとの lint 結果です。Ruff は十分高速なので、これがなくてもほとんど気にならないでしょう。

何かがおかしな動作をした場合は、rm -rf .mypy_cache .pytest_cache .ruff_cache で安全にリセットできます。

行き詰まった場合

これは自分の会社の帳簿用に作ったものですが、他の誰かの役に立つかもしれないので、きちんと書き残しました。

このようなものをセットアップしようとしていてうまくいかない場合、私はこの種の仕事を専門にしており、喜んでお話しします。

バグを見つけた場合や、ここに誤りがある場合は、issue を歓迎します。