PNPC-MCP-Tally-Prime

MCP(Model Context Protocol) 서버로, Claude가 TallyPrime의 내장 XML/HTTP 게이트웨이를 통해 데이터를 읽고 쓸 수 있게 해줍니다.

PNPC 내부 사용을 위해 vaijaaaaa/Tally-MCP-Server (ISC 라이선스)에서 포크했습니다. 원저작자의 고지 사항은 LICENSE를 참조하세요.

작동 방식

Claude Desktop  <--stdio-->   ┐
                               ├─ this MCP server  <--HTTP/XML-->  TallyPrime (localhost:9000)
Remote MCP client <--HTTP-->  ┘

로컬에서는 Claude Desktop이 이 서버를 stdio 프로세스로 실행합니다. 원격으로는 HTTP 서버로도 실행할 수 있습니다. 두 경우 모두, 도구 호출은 Tally의 XML 요청 형식으로 변환되어 Tally의 HTTP 게이트웨이로 전송되고, 정리된 JSON으로 반환됩니다. 또한 고정된 보고 도구 외에 임시 쿼리를 위한 선택적 로컬 SQL 캐시(PGLite)도 있습니다.

사전 요구 사항

• Node.js 18+

• TallyPrime이 설치 및 실행 중이고, 회사 데이터가 열려 있어야 함

• Tally의 HTTP 게이트웨이가 활성화되어 있어야 함: F1 (도움말) > 설정 > 연결 > 클라이언트/서버 구성에서 TallyPrime 역할을 둘 다 또는 서버로 설정하고, 포트는 9000(기본값)으로 설정합니다.

설정

npm install
npm run build

Claude Desktop 구성

옵션 A — 확장(권장): .dxt로 패키징하여 한 번의 클릭으로 설치합니다. docs/EXTENSION_PACKAGING.md를 참조하세요.

옵션 B — 수동 구성: Claude Desktop 구성 파일을 편집합니다.

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

추가:

{
  "mcpServers": {
    "pnpc-tally": {
      "command": "C:\\Users\\Lokesh\\node20\\node.exe",
      "args": ["C:\\Users\\Lokesh\\PNPC-MCP-Tally-Prime\\dist\\index.js"],
      "env": {
        "TALLY_URL": "http://localhost:9000"
      }
    }
  }
}

Claude Desktop을 다시 시작합니다. pnpc-tally 서버가 연결되었음을 나타내는 망치/도구 아이콘이 표시되어야 합니다.

사용 가능한 도구

총 17개의 도구 — 읽기(원장, 재고, 그룹, 바우처 유형, 코스트 센터, 일일 장부, 원장 바우처, 회사 정보, 손익계산서, 대차대조표, 합계잔액시산표, 재고 요약, 받을/지급할 어음), 쓰기(원장, 그룹, 재고 품목, 바우처 생성), SQL 캐시(sync_to_sql, query_sql). 인수를 포함한 전체 참조: docs/TOOLS.md.

날짜는 Tally의 규칙에 따라 DD-MM-YYYY 형식을 사용합니다.

원격 실행 (HTTP)

TALLY_MCP_TOKEN=<secret> npm run start:http

docs/HTTP_DEPLOYMENT.md를 참조하세요.

문서

• docs/ARCHITECTURE.md — 요청 흐름, 파일별 역할

• docs/TALLY_XML_GUIDE.md — Tally XML 게이트웨이 작동 방식 및 주의사항

• docs/TOOLS.md — 전체 도구 참조 및 새 도구 추가 방법

• docs/SQL_CACHE.md — PGLite SQL 캐시, 스키마, 예제

• docs/HTTP_DEPLOYMENT.md — 원격 HTTP 서버로 실행

• docs/EXTENSION_PACKAGING.md — .dxt Claude Desktop 확장으로 패키징

프로젝트 구조

src/
  tally.ts        Tally HTTP client: sends XML, handles connection/timeout errors
  clean.ts        Normalizes Tally's raw XML->JSON into predictable JSON
  templates.ts     Renders the Nunjucks XML templates in templates/
  db.ts             PGLite SQL cache: sync_to_sql / query_sql
  tools.ts        MCP tool definitions + XML request builders
  server.ts       Shared MCP Server construction (used by both entry points)
  index.ts        stdio entry point (local Claude Desktop)
  http-server.ts   HTTP entry point (remote clients)
templates/
  *.xml.njk       Nunjucks templates for each Tally XML request shape
manifest.json      Claude Desktop Extension (.dxt) manifest

환경 변수

문제 해결

• "TallyPrime에 연결할 수 없습니다" — Tally가 실행 중이 아니거나, HTTP 게이트웨이가 포트 9000에서 활성화되지 않았습니다.

• "Tally가 빈 응답을 반환했습니다" — Tally는 실행 중이지만 열린 회사 데이터가 없습니다.

• create_ledger / create_voucher가 오류와 함께 실패합니다 — 상위 그룹/원장 이름이 Tally에 있는 이름과 정확히 일치하는지 확인하세요(이름은 대소문자를 구분하며 정확히 일치해야 합니다).

로드맵 / 아직 지원되지 않는 기능

• 기존 바우처/원장/마스터 편집 또는 삭제

• 재고 바우처(재고 일지, 제조 일지 등)

• GST 관련 보고서(GSTR-1, GSTR-3B)

• 다중 회사 지원(현재는 항상 열려 있는 회사를 대상으로 함)