Qoyod MCP 서버

Claude를 قيود(Qoyod) 회계 프로그램에 공식 REST API(https://api.qoyod.com/2.0)를 통해 직접 연결하는 소형 MCP(Model Context Protocol) 서버입니다.

어느 호스팅에든 배포(deploy)한 후, 다음과 같은 HTTPS 링크를 얻게 됩니다:

https://your-app.onrender.com/mcp

이 링크를 Claude 설정에서 Custom Connector로 추가하면, Claude가 브라우저를 열 필요 없이 모든 대화에서 고객, 인보이스, 공급업체, 일일 분개 등을 읽고 생성할 수 있게 됩니다.

1) 제공되는 도구(Tools)

• qoyod_request — apidoc.qoyod.com에 문서화된 모든 리소스(Accounts, Products, Inventories, Vendors, Purchase Orders, Bills, Customers, Quotes, Invoices, Credit/Debit Notes, Receipts, Journal Entries...)를 다루는 범용(passthrough) 도구입니다.

• 빠른 사용을 위한 준비된 도구: qoyod_list_customers, qoyod_get_customer, qoyod_create_customer, qoyod_list_products, qoyod_list_invoices, qoyod_get_invoice, qoyod_create_invoice, qoyod_list_bills, qoyod_list_vendors, qoyod_list_journal_entries, qoyod_create_journal_entry, qoyod_list_accounts.

참고: Qoyod 일반 문서는 모든 리소스의 모든 필드를 상세히 언급하지 않습니다. 생성(create_*) 시 apidoc.qoyod.com을 통해 올바른 payload 형식을 확인하거나, 먼저 테스트 데이터로 qoyod_request를 통해 시도해 보세요.

Related MCP server: Piriod MCP Server

2) 로컬 실행(선택 사항, 배포 전 테스트용)

Node.js 18 이상이 필요합니다.

npm install
cp .env.example .env
# افتح .env وضع مفتاح الـ API الخاص بك من قيود (Settings > General Settings > API Key)
npm start

서버는 http://localhost:3000/mcp에서 실행됩니다.

3) 무료 호스팅에 배포(Deploy) — Render.com을 사용한 예시

1. render.com에서 무료 계정을 만드세요(또는 GitHub 계정으로 로그인).

2. 이 폴더를 새 GitHub 저장소에 업로드하세요(github.com에서 빈 저장소를 만든 후, git에 익숙하지 않다면 웹 인터페이스에서 직접 파일을 업로드할 수 있습니다).

3. Render 대시보드에서: New + → Web Service → 저장소를 선택하세요.

4. 설정:

   • Build Command: npm install

   • Start Command: npm start

   • Environment Variable: QOYOD_API_KEY를 추가하고 값은 Qoyod의 API 키를 입력하세요.

5. Deploy를 누르세요. 빌드가 완료되면 다음과 같은 링크를 얻습니다: https://qoyod-mcp-server.onrender.com

6. Claude에서 사용할 전체 MCP 링크는 다음과 같습니다: https://qoyod-mcp-server.onrender.com/mcp

다른 대안

거의 동일한 단계가 Railway, Fly.io, Cloudflare Workers에도 적용됩니다(Workers 환경에 맞게 약간의 수정 필요).

Render 무료 플랜 참고: 서버는 일정 시간 유휴 상태 후 "절전 모드"로 전환되며, 유휴 후 첫 요청에는 ~30-50초가 걸립니다. 항상 즉각적인 응답이 필요하다면 유료 플랜이나 서비스를 절전하지 않는 다른 호스팅이 필요합니다.

4) Claude에 연결하기

1. Claude 설정에서 Connectors(커넥터) 섹션을 찾아 → Add custom connector를 선택하세요.

2. 링크를 붙여넣으세요: https://your-app.onrender.com/mcp

3. 저장하세요. 이후 이 커넥터를 활성화한 모든 대화에서 Qoyod 도구가 Claude 도구 목록에 표시됩니다.

5) 보안

• 귀하의 API 키는 호스팅 환경 변수(QOYOD_API_KEY)로만 저장됩니다 — 코드에 노출되지 않으며 다른 어떤 당사자에게도 전송되지 않습니다.

• 신뢰하지 않는 사람과 /mcp 링크를 공유하지 마세요. 이 링크는 연결된 Qoyod 계정에 (키 권한에 따라) 완전한 접근 권한을 부여합니다.

• 키가 유출되었다고 의심되면 Qoyod → 일반 설정 → Generate New Key로 이동하여 이전 키를 즉시 무효화하는 새 키를 발급하세요.