flow-team-mcp

Flow Team OpenAPI를 MCP(Model Context Protocol) 클라이언트에서 사용할 수 있게 해주는 로컬 MCP 서버입니다.

Flow API 문서: https://api.flow.team/docs

현재 릴리스: v0.1.0

주요 기능

• Flow OpenAPI 엔드포인트 목록을 검색하고 메타데이터를 확인할 수 있습니다.
• FLOW_API_KEY를 사용해 Flow OpenAPI를 직접 호출할 수 있습니다.
• 프로젝트 API는 전용 MCP 도구로 더 쉽게 사용할 수 있습니다.
  • 프로젝트 목록 조회
  • 특정 사용자가 참여 중인 프로젝트 조회
  • 프로젝트 참여자 조회
  • 프로젝트 컬럼 / 상태 컬럼 조회
  • 프로젝트 생성
  • 프로젝트 참여자 추가

준비 사항

• Node.js 20 이상 권장
• npm
• Flow Developer Portal에서 발급한 API Key

Git, Node.js, npm이 아직 설치되어 있지 않다면 Windows/macOS 설치 가이드를 먼저 확인하세요.

API Key는 서버 실행 환경변수로만 주입하세요. .env, 설정 파일, README 예시 등에 실제 키를 커밋하지 마세요.

로컬 설정

git clone <repository-url>
cd flow-team-mcp
npm install
npm run build

빌드가 끝나면 MCP 서버 엔트리포인트는 dist/index.js입니다.

로컬에서 서버 프로세스만 확인하려면 다음 명령을 실행할 수 있습니다.

FLOW_API_KEY="YOUR_FLOW_API_KEY" npm start

이 서버는 stdio 기반 MCP 서버라서 터미널에서 직접 실행하면 대기 상태로 보이는 것이 정상입니다. 실제 사용은 MCP 클라이언트 설정을 통해 연결합니다.

MCP 클라이언트 설정

아래 예시는 로컬에 clone한 저장소를 직접 실행하는 방식입니다. args의 경로는 본인 PC의 절대 경로로 바꾸세요.

{
  "mcpServers": {
    "flow-team": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/flow-team-mcp/dist/index.js"],
      "env": {
        "FLOW_API_KEY": "YOUR_FLOW_API_KEY"
      }
    }
  }
}

예를 들어 이 저장소가 /Users/me/Projects/flow-team-mcp에 있다면:

{
  "mcpServers": {
    "flow-team": {
      "command": "node",
      "args": ["/Users/me/Projects/flow-team-mcp/dist/index.js"],
      "env": {
        "FLOW_API_KEY": "YOUR_FLOW_API_KEY"
      }
    }
  }
}

클라이언트별 자세한 설정 방법:

• Windows/macOS 설치 가이드
• Codex에서 사용하기
• Claude Code에서 사용하기

npm link 사용하기

전역 명령으로 연결하고 싶다면:

npm install
npm run build
npm link

그 다음 MCP 클라이언트 설정에서 flow-team-mcp 명령을 사용할 수 있습니다.

{
  "mcpServers": {
    "flow-team": {
      "command": "flow-team-mcp",
      "env": {
        "FLOW_API_KEY": "YOUR_FLOW_API_KEY"
      }
    }
  }
}

환경변수

이름	필수	기본값	설명
FLOW_API_KEY	예	-	Flow OpenAPI 호출에 사용할 API Key입니다.
FLOW_API_BASE_URL	아니오	https://api.flow.team	Flow API base URL입니다. 테스트 또는 프록시 환경에서만 변경하세요.

각 도구 호출에서 apiKey, baseUrl 입력값을 직접 넘기면 환경변수보다 우선합니다.

제공 도구

공통 도구

도구	설명
list_flow_endpoints	서버에 등록된 Flow OpenAPI 엔드포인트 목록을 조회합니다. version, group, method, search로 필터링할 수 있습니다.
get_flow_endpoint	엔드포인트 ID로 HTTP method, path, docs URL 같은 메타데이터를 조회합니다.
flow_request	endpointId 또는 직접 지정한 method / path로 Flow OpenAPI를 호출합니다.

프로젝트 도구

도구	설명
get_project_api_schema	프로젝트 API의 request, response, error 문서 정보를 조회합니다.
list_projects	Flow 프로젝트 목록을 조회합니다.
list_participant_projects	특정 사용자가 참여 중인 프로젝트 목록을 조회합니다.
get_project_participants	특정 프로젝트의 참여자 목록을 조회합니다.
get_project_columns	특정 프로젝트의 컬럼 목록을 조회합니다.
get_project_status_columns	특정 프로젝트의 상태 컬럼 목록을 조회합니다.
create_project	새 Flow 프로젝트를 생성합니다.
add_project_participants	프로젝트에 참여자를 추가합니다.

프롬프트 예시

MCP 클라이언트에서 다음처럼 요청할 수 있습니다.

Flow 프로젝트 목록 조회해줘.

projectId가 123000인 프로젝트의 참여자 목록 조회해줘.

Flow API에서 chats 관련 endpoint 목록 찾아줘.

Flow endpoint id가 post_v1_bots_botId_notifications인 API 메타데이터 보여줘.

도구 입력 예시

list_projects

{
  "cursor": "0"
}

get_project_participants

{
  "projectId": "123000"
}

create_project

{
  "registerId": "company@company.name",
  "title": "테스트 프로젝트",
  "description": "이 프로젝트는 OpenAPI로 생성되었습니다.",
  "defaultTab": "feed"
}

add_project_participants

{
  "projectId": "123000",
  "registerId": "company@company.name",
  "participants": [
    {
      "participantId": "user@company.name"
    }
  ]
}

flow_request

endpointId를 사용하는 방식:

{
  "endpointId": "get_v1_projects_projectId_participants",
  "pathParams": {
    "projectId": "123000"
  }
}

직접 method와 path를 지정하는 방식:

{
  "method": "GET",
  "path": "/v1/projects/{projectId}/participants",
  "pathParams": {
    "projectId": "123000"
  }
}

개발

npm run typecheck
npm run build

주요 파일 구조:

src/
  index.ts              # MCP 서버 부트스트랩
  endpoints.ts          # Flow API endpoint catalog
  flow-client.ts        # x-flow-api-key, path/query/body 처리, fetch 공통화
  mcp-result.ts         # MCP 응답 포맷 유틸
  schemas/
    projects.ts         # 프로젝트 API 문서 메타데이터와 Zod input schema
  tools/
    generic.ts          # list_flow_endpoints, get_flow_endpoint, flow_request
    projects.ts         # 프로젝트 전용 MCP tools

문제 해결

FLOW_API_KEY 환경변수 또는 apiKey 입력값이 필요합니다.

MCP 클라이언트 설정의 env.FLOW_API_KEY에 Flow API Key가 들어있는지 확인하세요. 클라이언트를 재시작해야 새 설정이 반영되는 경우가 많습니다.

Cannot find module .../dist/index.js

npm run build를 먼저 실행했는지 확인하세요. TypeScript 소스는 src/에 있고, MCP 클라이언트는 빌드 결과물인 dist/index.js를 실행합니다.

MCP 클라이언트에서 도구가 보이지 않음

• MCP 설정 JSON 문법이 올바른지 확인하세요.
• args가 절대 경로인지 확인하세요.
• 설정 변경 후 MCP 클라이언트를 완전히 재시작하세요.
• 로컬 저장소 위치를 옮겼다면 args 경로도 함께 수정하세요.

참고 사항

• 현재 서버는 stdio transport를 사용합니다.
• Flow API 응답은 원본 HTTP 상태, 헤더, body를 포함한 JSON 형태로 반환됩니다.
• 일부 API는 Flow 계정, 이용기관, 프로젝트 권한에 따라 실패할 수 있습니다.

라이선스

ISC