freeagent-mcp-remote

이 "커넥터"는 Claude가 제 FreeAgent 데이터에 접근할 수 있도록 만들었습니다. 현재는 내부 도구이지만, 다른 사람들에게도 유용할 수 있도록 명확하고 일반 대중을 대상으로 작성하려고 노력했습니다. 설정이나 적용에 도움이 필요하거나, 비즈니스를 위한 유사한 도구를 원하신다면 질문하기를 이용하세요.

samaxbytez/freeagent-mcp에서 영감을 받았습니다. 처음에는 그 위에서 개발할 생각이었지만, [https://gofastmcp.com]와 Python을 사용하여 처음부터 다시 시작하기로 결정했습니다.

• WIP — "작업 진행 중"이라는 뜻입니다. 개발자들이 사용하는 용어로, 이 README 전체에서 아직 사용할 수 없는 기능을 표시하는 데 사용됩니다. "곧 제공 예정"과 같은 의미입니다.

사용 가능한 기능

둘은 설정을 공유하므로, 아래 단계를 따르면 오늘 바로 작동하는 절반을 얻을 수 있습니다.

작동 방식

이 프로젝트는 FreeAgent와 Claude(또는 다른 AI 제공자) 사이에 위치하여 번역기 역할을 하는 작은 서버입니다. 연결되면 Claude에게 *"3월 은행 거래 중 아직 설명되지 않은 것은 무엇인가요?"*와 같은 질문을 할 수 있고, 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는 액세스를 승인한 후 브라우저를 이 주소로 다시 보내므로 정확히 일치해야 합니다. 끝에 슬래시가 있으면 작동하지 않습니다.

   그 주소는 명령줄 도구가 사용하는 주소입니다. 브라우저가 사용자 자신의 컴퓨터로 돌아오기 때문입니다. 커넥터는 배포된 후에는 공개 웹 주소로 접근되므로 자체 리디렉션 URI를 등록해야 합니다 — <the container's URL>/auth/callback. 지금은 할 일이 없습니다. 배포 런북에서 필요한 시점에 다룹니다. 나중에 두 개의 다른 주소를 보고 하나가 실수라고 생각하지 않도록 알아두는 것만으로 충분합니다.

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분 정도 걸리지만 이후에는 거의 즉시 완료됩니다.

uv run <command>는 해당 환경 안에서 명령을 실행합니다. 아래의 모든 명령이 uv run으로 시작하는 이유입니다.

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로 설정하면 샌드박스를 가리키게 되며, 로그인 엔드포인트도 자동으로 따라가므로 둘이 섞일 수 없습니다. 데이터를 쓰는 모든 작업 전에 해두는 것이 좋고, 읽기 전용 작업에는 그럴 가치가 없습니다. 샌드박스에는 실제 데이터가 없기 때문입니다.

명령줄 도구 사용하기

이 기능은 지금 사용할 수 있습니다. 로그인을 처리하면서 터미널에서 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

전체 스위트는 약 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 문서에는 누락, 모순, 그리고 최소 두 개의 복사-붙여넣기 오류가 있습니다. 따라서 커넥터의 도구는 문서가 아닌 실제 API 응답을 기준으로 설계되었습니다. 위의 명령줄 도구가 바로 그 용도입니다. scripts/freeagent_api_caller.py는 로컬 전용이며 절대 배포되어서는 안 됩니다. 이 파일이 배포된 서버에 도달하면 실패하는 테스트가 있습니다.

알아두기

캐시

도구를 실행하면 세 개의 디렉터리가 나타납니다. 모두 생성된 파일이며 gitignore에 포함되어 있고 프로그램 입력으로 사용되지 않습니다. 이 중 하나를 삭제해도 다음 실행이 느려질 뿐 아무 손해가 없습니다.

• .mypy_cache/ — mypy가 각 파일의 유형에 대해 학습한 내용입니다. 변경되지 않은 파일을 다시 검사할 때 새로 분석하는 대신 캐시를 읽습니다. 가장 중요한 항목입니다. 이것이 없으면 모든 실행마다 모든 의존성의 유형 정보를 다시 분석합니다.

• .pytest_cache/ — 지난번에 실패한 테스트 목록입니다. pytest --lf(last-failed)와 --ff(failed-first)를 가능하게 하는 요소이므로 실패한 테스트만 반복할 수 있습니다.

• .ruff_cache/ — 파일별 린트 결과입니다. Ruff는 충분히 빨라서 이 캐시가 없어도 거의 느끼지 못할 것입니다.

무언가 이상하게 작동한다면 rm -rf .mypy_cache .pytest_cache .ruff_cache를 실행하는 것이 안전한 초기화 방법입니다.

막히면

이 도구는 제 회사의 장부를 위해 만들었고, 다른 누군가에게 유용할 경우를 대비해 제대로 문서화했습니다.

이와 같은 것을 설정하려고 하는데 잘 되지 않는다면, 저는 이런 종류의 작업을 전문적으로 하고 있으며 기꺼이 상담해 드리겠습니다.

버그를 발견했거나 여기에 잘못된 내용이 있다면 이슈를 등록해 주세요.