FreeAgent MCP

[!WARNING] 이 프로젝트는 100% 바이브 코딩으로 작성되었습니다. 모든 것을 테스트하고 코드를 살펴보진 않았습니다. 작동하지 않을 수도 있습니다. 사용에 따른 책임은 본인에게 있습니다.

FreeAgent 회계 데이터를 AI 클라이언트(Claude Desktop, ChatGPT 데스크톱 앱, 또는 stdio를 통해 MCP를 말하는 그 밖의 어떤 클라이언트)에 노출하는 로컬, 읽기 전용 MCP 서버입니다. 이를테면 "명목 코드 907에 £4,200이 왜 그대로 남아 있지?" 같은 질문을 툴고, 모델이 관련 거래 내역을 자세히 파고들도록 수 있습니다.

읽기 전용은 HTTP 클라이언트 계층에서 강제됩니다. 클라이언트는 get() 메서드만 노출하고, 그 외에는 아직 아무것도 노출하지 않습니다. 다른 동사(verb)를 호출하려는 시도는 예외를 발생시킵니다. 모든 도구는 읽기 전용 및 멱등(idempotent)임이 명시되어 있습니다. 회계 데이터를 수정할 수 있는 코드 경로는 존재하지 않으며, 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 웹에서는 보이지 않습니다.

도구

기타 명령어

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회/시간)를 빠르게 소진하지 않습니다.