1c-odata-mcp — OData를 통한 1C:Enterprise용 범용 MCP 서버 - Insights

🇬🇧 요약: 표준 OData 인터페이스를 통해 1C:Enterprise를 모든 MCP 클라이언트(Claude, Cursor, VS Code, 로컬 모델 등)에 연결하는 MCP 서버입니다. 회계 데이터베이스(채무자, 판매, 세금, 현금 흐름, 계정 순환, 전표 전기)에 일반 언어로 질문하고 숫자를 받거나, 명시적으로 옵트인하여 쓰기 작업을 할 수 있습니다. 기본값은 읽기 전용입니다. npx -y 1c-odata-mcp로 실행합니다. OData가 게시된 모든 1C(클라우드, SQL 또는 로컬 파일 기반)에서 작동합니다.

표준 OData 인터페이스를 통한 1C:Enterprise용 MCP 서버 (Model Context Protocol). Claude, Cursor, VS Code, JetBrains, Ollama, LM Studio와 같은 모든 MCP 클라이언트에서 1C 데이터를 자연어로 처리할 수 있게 해줍니다. 거래처, 문서, 잔액, 채무자, 판매, 자금 흐름, 총계정원장(ОСВ), 전표 전기 등에 대해 질문할 수 있으며 — 명시적으로 활성화하면 생성/수정하는 물론, 전표를 전기하고 결제를 등록하며 처리할 수도 있습니다.

만약 1C를 신경망/AI에 연결하는 방법, 1C OData용 준비된 커넥터 또는 1C와 Claude의 **통합(Integration)**을 1C 측에서 프로그래밍하지 않고 찾고 있었다면, 이것이 바로 그것입니다.

🔌 모든 MCP 클라이언트: Claude Desktop 및 Claude Code, Cursor, VS Code (Continue/Cline), JetBrains — 그리고 로컬 모델 (Ollama, LM Studio)
🔐 데이터는 사용자에게 남아 있습니다 — 서버는 로컬 프로세스이며 사용자의 데이터베이스에만 연결됩니다. 로컬 모델을 사용할 경우 데이터가 네트워크를 벗어나지 않습니다.
🏢 여러 개의 정보 데이터베이스 및 조직(법인) 동시 처리
🔒 기본적으로 읽기 전용입니다. 쓰기는 이중 안전장치와 사전 미리보기를 거쳐야 합니다.
🚀 한 번의 명령으로 실행: npx -y 1c-odata-mcp
⚙️ 1C 측에 아무것도 설치할 필요가 없습니다 — 공개된 OData만 있으면 됩니다 (COM 연결, SQL 접근 없음)

📘 OData 설정, 게시 및 Claude 연결 방법은 docs/CONNECTING.md를 확인하세요. 여기서는 프로젝트 자체, 기능 및 제한 사항에 대해 설명합니다.

모든 1C 버전에 적용 가능

컨넥터는 1C와 오직 OData를 통해서만 통신합니다. 이 기능이 활성화되면 사용자의 데이터베이스가 어떻게 배포되었든 동일하게 작동합니다:

사용자 1C	작동에 필요한 것	난이도
클라우드 / 호스팅 (Scloud, 1cFresh, 1C 임대)	OData에 제공자가 포함되어야 합니다 — 관리자 페이지의 체크박스 또는 요청을 통해 활성화 가능	🟢 낮음
...
데이터 저장소 유형(파일 기반 또는 SQL) 자체는 난이도를 변화시키지 않습니다 — 중요한 것은 OData 웹 게시가 이루어졌는지 여부입니다. OData를 활성화하지 않으면 컨넥터가 작동할 수 없습니다 (COM을 사용하거나 SQL에 직접 접근하지 않기 때문).

➡️ 각 옵션별 단계별 지침은 **docs/ODATA-SETUP.md**에서 확인하세요. 데이터베이스 주소, 계정 및 Claude 연결 방법은 **docs/CONNECTING.md**에 있습니다.

왜 필요한가요?

1C의 원시 OData는 수백 개의 기술적인 EntitySet과 키릴 문자 이름(Catalog_Контрагенты, Document_РеализацияТоваровУслуг, AccumulationRegister_ТоварыНаСкладах) 및 GUID 키로 구성되어 있습니다. 이 상태로는 채팅에서 작업할 수 없으며, 모든 보고서에 맞춰 코드를 작성하는 것은 시간이 오래 걸립니다.

서버가 모든 기술을 이해하기 쉬운 도구들로 숨겨 놓았습니다. 일반 언어로 질문하면 AI가 필요한 도구를 스스로 선택하고, OData 데이터베이스에 접근하여 준비된 답변을 반환합니다. 임원에게는 비즈니스 개요를 빠르게 파악할 수 있게 하고, 회계 담당자에게는 통제 하에 문서 생성의 루틴 작업을 처리하게 합니다.

기능

분석 및 읽기 (기본값):

'매출채권 보여줘' → 거래처별 62 계정 잔액
'거래처 로마슈카 이력' → 모든 문서 및 상호 정산 내역
'창고 재고 현황' → 품목별 수량 및 금액
'5월 매출', '분기 돈의 움직임' → 기간별 총계
'분기 51 계정 원장', '이 문서가 만든 분개는 뭐야?' → 회계 장부 기록 및 회계 장부에서 가져온 분개서
'문서 작성 시점과 주체' → 감사용 문서 연혁
거래처 및 문서 검색, 객체 카드, 데이터베이스 지도

작동 (기록 활성화 시, 항상 사전 미리보기 및 확인 필요):

'거래처 ООО 로마슈카를 만들고, ИНН …, 전화번호, 이메일, 계산 계좌, 대표이사'
'구매자에게 1000원짜리 3개 청구서 발행' → 초안 문서
'공급업체로부터 입금 및 구매자에게 매출 처리', '문서 전표' → 분개는 1C가 자체적으로 생성함
'구매자 반품 처리', '창고 간 이동', '입고/출고/재고 조사'
'대금 지급 처리', '계산 계좌에서 차감', '입금/출금 현금 영수증'
'매출에 대한 세금 계산서 발행', '용역 제공 증명서'
'작년 7월의 문서를 작년 6월처럼 만들고, 기간과 수량 변경' → 모든 명세(행 내용, 회계 계정, 은행 계좌)가 포함된 이전 문서 사본 — 이렇게 매달 문서를 발행함
속성 및 문서 행 수정; 전표 처리 및 삭제 표시

읽기는 모든 유형의 문서 (위 목록에 국한되지 않음)가 가능합니다. '5월 반품 보여줘', '이동 내역 찾아줘' 등.

전체 목록은 도구 섹션에서 확인하세요.

대화 예시

아래는 Claude Desktop이지만, 대화 내용은 모든 MCP 클라이언트에서 동일하게 보입니다.

당신: 구매자 중 누가 가장 많이, 그리고 얼마나 많은지?
Claude: (read.analytics.get_debtors 호출) 오늘 날짜의 주요 채무자:
        1. ООО «로마슈카» — 1,240,500 ₽
...

빠른 시작

MCP가 처음이신가요? MCP(Model Context Protocol)는 AI 어시스턴트가 외부 도구에 연결하는 공개 프로토콜입니다. 여기서 '도구'란 귀하의 1C를 의미합니다. 어시스턴트가 필요한 함수를 스스로 호출하고 응답을 반환합니다. 코딩할 필요가 없습니다 — 아래 세 단계를 따르세요.

1C에서 OData를 게시하고, 필요한 객체를 '구성'에 추가하세요 (자세한 내용은 docs/CONNECTING.md; OData가 아직 활성화되지 않았다면 docs/ODATA-SETUP.md 참고).
Claude Desktop (claude_desktop_config.json)에 서버를 작성하고, 주소와 자격 증명을 입력하세요:
```
{
  "mcpServers": {
    "1c-odata": {
```
1
2
3
4

...

3. **Claude Desktop**을 완전히 재시작하고,

**판매 및 구매 문서 라인(Строки документов продажи и закупки)**은 다음을 받습니다:

- `content` — **'내용(Содержание)'** 속성입니다. 이 텍스트가 청구서와 UPD에 인쇄됩니다 (예: '계약 번호 87...에 따른 2026년 7월 서비스 이용료'). 1C 자체가 이를 채우지 않으므로, 서비스의 경우 명시적으로 지정해야 합니다.
- `incomeAccount` / `expenseAccount` — **1C와 동일한 코드**로 입력하는 수입 및 지출 계정(`90.01.2`, `90.02.2`) 또는 `Ref_Key`를 사용합니다. 이들은 문서 전체에 대해 지정할 수도 있습니다. 우선순위는 다음과 같습니다: 라인 → 문서 → '상품 계정(Счета учёта номенклатуры)' 레지스터 → `90.01.1` / `90.02.1`. 계정은 판매 문서에만 적용 가능하며, 결제서나 입금 내역에서는 사용하지 않습니다.

- `orgBankAccount` (구매자에게 발송되는 계좌, 실적, 증명서) — 청구 시 속성으로 인쇄되는 조직의 은행 계좌입니다. 이름, 계좌 번호 또는 `Ref_Key`로 지정할 수 있습니다. 아무것도 지정하지 않으면 **기본** 조직 계좌가 사용됩니다.

`write.document.add_document_line`과 `remove_document_line`은 표 부분을 재구성하면서 **이전 라인의 속성(내용, 계정, 상품 그룹)**을 유지합니다. `update_document_lines`는 라인을 통째로 교체하므로, 이 경우 다시 지정해야 합니다. 라인은 문서에 채워진 표 부분에 작성됩니다: 서비스 증명서의 경우 '서비스(Услуги)', 상품 문서의 경우 '상품(Товары)'입니다.

**매월 반복되는 문서(Ежемесячно повторяющиеся документы)**는 `write.document.copy_document`를 통해 더 쉽게 발행할 수 있습니다. 이 함수는 이전 문서를 샘플로 가져와 은행 계좌, 담당자, 배송 주소, 추가 청구 조건 등 스키마 `create_*`에 없는 속성까지 모든 속성을 전송합니다. 날짜(`date`), 헤더 속성(`fields`), 라인 번호별 수정 사항(`lines`)만 변경됩니다. 계산서의 경우 복사본은 원본 문서에서 가져오며, 만약 `fields`에서 계약을 변경하면 새 계약 설정에 따릅니다.

**거래처 정산 명세서** (62, 60, 76 등…) 서버는 1C 설정에서 레지스터를 가져옵니다. «거래처 정산 계정»은 먼저 계약 설정을 거친 후 거래처, 조직 및 일반 수준으로, 계약 통화를 고려하여 작성됩니다. 사전 미리보기에서는 명세서가 어디에서 왔는지 작성합니다. 만약 레지스터가 OData에 게시되지 않았다면 표준 62.01/62.02 및 60.01/60.02를 사용합니다.**다른 계정 계획 또는 거래 유형.** `ODATA_ACCOUNTING_CONFIG`와 `ODATA_DB_<이름>_ACCOUNTING_CONFIG`는 계정 계획, 회계 레지스터, 기본 계정 코드, 분석 접두사 및 명세서/결제 거래 유형을 정의합니다. 설정하지 않으면 이전 러시아 연방(RF)의 회계 값을 유지합니다. 벨라루스에 대한 매개변수, 우선순위 및 종합 예시는 [회계 설정](docs/ACCOUNTING.md)에서 확인할 수 있습니다.

---

## 보안

**기본적으로 서버는 읽기 전용(read-only)으로 작동합니다.** 쓰기는 **두 개의 독립적인 안전장치**를 통해 의식적으로 활성화됩니다:

1. **전역 스위치** `READ_ONLY=false`.
2. **개별 데이터베이스 플래그** `ODATA_DB_<이름>_WRITABLE=true` — 이 플래그가 없는 데이터베이스는 전역 스위치가 해제되어도 읽기 전용 상태를 유지합니다. 이렇게 하면 한 데이터베이스(예: 개인사업자/IP)에 대해서만 쓰기를 허용하고 다른 데이터베이스(예: 유한회사/OOO)는 보호할 수 있습니다.

추가적인 쓰기 시:

- **기본 dry-run** — 생성(및 문서 라인 추가/삭제) 사전 검토는 `operationId`를 반환합니다. 기록을 전송할 때는 이 ID와 동일한 인자들을 `confirm=true`와 함께 전달해야 합니다. 네트워크 오류가 발생하면, 새로운 사전 검토를 실행하지 말고 같은 ID로 확인 절차를 반복하십시오.;
- **POST의 불확실한 결과 방지** — 로컬 로그는 요청과 결과를 기록합니다. 동일한 ID와 인자로 재시도할 경우, 두 번째 POST 없이 저장된 결과를 반환합니다. 연결이 끊겼고 원본을 알 수 없는 경우, 서버는 재시도를 차단하고 1C에서 결과를 확인하도록 요청합니다. 이 확인은 `write.operation.status`를 통해 이루어집니다: 생성되는 MCP 객체에 자체적으로 `Ref_Key`(UUIDv1, 사전 검토 시 할당됨)가 지정되므로, 동일한 1C 참조 키로 재시도할 경우 고유 인덱스 레벨에서 거부되며, 시간 초과 후에는 객체가 단순 GET으로 접근 가능해집니다 (문서와 명칭(справочник) 모두 해당). 문서 라인의 수정은 라인 수로 확인됩니다. 원한다면 문서의 '설명' 필드에 `[op:<operationId>]`라는 가시적 마커 (`ODATA_WRITE_OPERATION_MARKER=true`)를 추가할 수 있습니다.;
- **기본 계약** — 만약 `contractRef`가 지정되지 않았고, 거래처와 일치하는 적절한 계약이 단 하나만 존재한다면 (유형이 '구매자와의'/'공급자와의'이고 같은 조직일 경우), 이는 1C 양식과 같이 자동으로 채워집니다. 그렇지 않은 경우, 사전 검토에서 경고합니다: 계약 없이는 1C 문서가 처리되지 않습니다.;
- **소프트 삭제** — `write.entity.mark_for_deletion`은 표시를 설정합니다 (1C와 동일). 강제적인 `DELETE`는 없습니다.;
- 1C 측에서는 'OData 구성'에 필요한 객체만 포함되며, 1C 사용자에게는 쓰기 권한이 있어야 합니다.

**데이터 개인 정보 보호.** 서버는 사용자의 장치에서 실행되는 로컬 프로세스입니다. 오직 사용자의 1C 데이터베이스(Basic 인증 방식)에 접속하여 데이터를 MCP 클라이언트로 전송합니다. 프로젝트의 외부 서버는 체인상에 없습니다. **로컬 모델** (Ollama, LM Studio)을 사용하는 경우, 1C 데이터는 아예 사용자 네트워크를 벗어나지 않습니다. 비밀 정보는 `.env` 파일(또는 `env` 설정 블록)에서만 가져옵니다; 암호와 인증 헤더는 로그에 기록되지 않습니다.

1c-odata-mcp — OData를 통한 1C:Enterprise용 범용 MCP 서버

요약

핵심 포인트

모든 1C 버전에 적용 가능

왜 필요한가요?

기능

대화 예시

빠른 시작

댓글

모든 1C 버전에 적용 가능

왜 필요한가요?

기능

대화 예시

빠른 시작