터치디자이너 MCP

TouchDesigner용 MCP(Model Context Protocol) 서버 구현입니다. AI 에이전트가 TouchDesigner 프로젝트를 제어하고 운영할 수 있도록 하는 것이 목표입니다.

영어 / 일본어

개요

TouchDesigner MCP는 AI 모델과 TouchDesigner WebServer DAT 간의 브리지 역할을 하여 AI 에이전트가 다음을 수행할 수 있도록 합니다.

노드 생성, 수정 및 삭제
쿼리 노드 속성 및 프로젝트 구조
Python 스크립트를 통해 TouchDesigner를 프로그래밍 방식으로 제어합니다.

용법

Node.js가 설치되어 있어야 합니다.

1. touchdesigner-mcp-server 패키지를 설치하세요

mkdir some && cd ./some (필요한 경우) npm install touchdesigner-mcp-server

2. TouchDesigner에 연결

TouchDesigner에 mcp_webserver_base.tox를 넣으세요

TouchDesigner를 시작하고 td/mcp_webserver_base.tox 구성 요소를 TouchDesigner 프로젝트 바로 아래에 가져옵니다. 예: /project1/mcp_webserver_base 에 배치합니다.

tox를 가져오면 API 서버 컨트롤러와 같은 모듈을 로드하는 td/import_modules.py 스크립트가 트리거됩니다.

TouchDesigner 메뉴에서 Textport를 열어 부팅 로그를 확인할 수 있습니다.

3. TouchDesigner MCP 서버 구성

TouchDesigner를 실행한 상태에서 AI 에이전트(Claude Desktop, Cursor, VSCode CopilotChat 등)를 구성하여 MCP 서버에 연결합니다.

예: Claude Desktop

지엑스피1

Windows 시스템에서는 C:와 같은 드라이브 문자를 포함하세요. 예: C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js

MCP 서버가 인식되면 설정이 완료된 것입니다. 인식되지 않으면 에이전트를 다시 시작하세요. 시작 시 오류가 발생하면 TouchDesigner를 시작한 후 에이전트를 다시 시작해 보세요. API 서버가 TouchDesigner에서 실행 중이면 에이전트는 제공된 도구를 통해 TouchDesigner를 사용할 수 있습니다.

MCP 서버 기능

이 서버는 MCP(Model Context Protocol)를 통해 TouchDesigner에서 작업을 수행할 수 있도록 하며 다양한 구현 문서에 대한 참조를 제공합니다.

도구

도구를 사용하면 AI 에이전트가 TouchDesigner에서 작업을 수행할 수 있습니다.

도구 이름	설명
`create_td_node`	새로운 노드를 만듭니다.
`delete_td_node`	기존 노드를 삭제합니다.
`exec_node_method`	노드에서 Python 메서드를 호출합니다.
`execute_python_script`	TD에서 임의의 Python 스크립트를 실행합니다.
`get_td_class_details`	TD Python 클래스/모듈에 대한 세부 정보를 얻으세요.
`get_td_classes`	TouchDesigner Python 클래스 목록을 가져옵니다.
`get_td_info`	TD 서버 환경에 대한 정보를 얻으세요.
`get_td_node_parameters`	특정 노드의 매개변수를 가져옵니다.
`get_td_nodes`	상위 경로 아래의 노드를 가져옵니다(선택적으로 필터링).
`update_td_node_parameters`	특정 노드의 매개변수를 업데이트합니다.

프롬프트

프롬프트는 AI 에이전트가 TouchDesigner에서 특정 작업을 수행하기 위한 지침을 제공합니다.

프롬프트 이름	설명
`Search node`	노드에 대한 퍼지 검색을 수행하고 이름, 패밀리, 유형을 기반으로 정보를 검색합니다.
`Node connection`	TouchDesigner 내에서 노드를 연결하는 방법에 대한 지침을 제공합니다.
`Check node errors`	지정된 노드의 오류를 확인하고, 자식 노드가 있는 경우 해당 자식 노드에 대해서도 재귀적으로 오류를 확인합니다.

자원

구현되지 않음

개발자를 위한

MCP 서버 코드 빌드

저장소를 복제합니다

git clone https://github.com/8beeeaaat/touchdesigner-mcp.git

종속성 설치

cd touchdesigner-mcp
npm install

환경 파일 설정 및 빌드

# Copy the template and adjust TD_WEB_SERVER_URL as needed
cp dotenv .env

# Build the project (generates API client/server schemas and compiles MCP resources)
# Make sure the Docker daemon is running before executing this command
npm run build

터치디자이너 설정

1. 코드 생성:

npm run build 실행하여 다음 코드를 생성합니다.

MCP 서버 코드
TouchDesigner WebServer DAT용 API 서버 코드

2. MCP 서버용 WebServer를 TouchDesigner로 가져옵니다.

TouchDesigner를 시작하고 td/mcp_webserver_base.tox 컴포넌트를 프로젝트 바로 아래에 가져오세요. tox를 가져오면 API 서버 컨트롤러와 같은 모듈을 로드하는 td/import_modules.py 스크립트가 실행됩니다.

3. API 서버 작동 확인:

td/modules 디렉터리의 Python 모듈이 mcp_webserver_base 구성 요소에서 접근 가능한지 확인하세요. npm run test 실행하여 MCP 서버 코드와 TouchDesigner 연결에 대한 단위 및 통합 테스트를 실행하세요. TouchDesigner 메뉴에서 Textport를 열어 통신 로그를 확인할 수 있습니다.

npm run dev 사용하여 @modelcontextprotocol/inspector로 디버깅할 수 있습니다.

팁: mcp_webserver_base.tox 에는 MCP 서버와 TouchDesigner를 연결하도록 구성된 웹 서버 DAT가 포함되어 있습니다. 이 DAT가 .env 파일의 TD_WEB_SERVER_URL 에 지정된 포트(기본값: 9981 )에서 활성화되어 실행 중인지 확인하세요. 포트를 변경하려면 다음 단계를 따르세요.

.env 에서 TD_WEB_SERVER_PORT 변경하세요
npm run build 다시 실행하세요.
mcp_webserver_base(WebServer DAT)에서 포트를 변경하고 DAT를 다시 시작합니다.

MCP 호환 AI 에이전트와 연결

TouchDesigner를 실행하고 AI 에이전트(Cursor, Claude Desktop, VSCode CopilotChat 등)를 구성하여 MCP 서버에 연결합니다.

예: Claude Desktop

{
  "mcpServers": {
    "dev_touchdesigner": {
      "args": [
        "/path/to/your/touchdesigner-mcp/dist/index.js", // <-- Replace with the absolute path to /dist/index.js after build
        "--stdio"
      ],
      "command": "node",
      "transportType": "stdio"
    }
  }
}

Windows 시스템에서는 C:와 같은 드라이브 문자를 포함하세요. 예: C:\\path\\to\\your\\touchdesigner-mcp\\dist\\index.js

설정 후 프로젝트 구조

├── src/                       # MCP server source code
│   ├── api/                  # OpenAPI spec for TD WebServer
│   ├── core/                 # Core utilities (logger, error handling)
│   ├── features/             # MCP feature implementations
│   │   ├── prompts/         # Prompt handlers
│   │   ├── resources/       # Resource handlers
│   │   └── tools/           # Tool handlers (e.g., tdTools.ts)
│   ├── gen/                  # Code generated from OpenAPI schema for MCP server
│   ├── server/               # MCP server logic (connections, main server class)
│   ├── tdClient/             # TD connection API client
│   ├── index.ts              # Main entry point for Node.js server
│   └── ...
├── td/                        # TouchDesigner related files
│   ├── modules/              # Python modules for TouchDesigner
│   │   ├── mcp/              # Core logic for handling MCP requests in TD
│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
│   │   │   └── services/    # Business logic (api_service.py)
│   │   ├── td_server/        # Python model code generated from OpenAPI schema
│   │   └── utils/            # Shared Python utilities
│   ├── templates/             # Mustache templates for Python code generation
│   ├── genHandlers.js         # Node.js script for generating generated_handlers.py
│   ├── import_modules.py      # Helper script to import API server modules into TD
│   └── mcp_webserver_base.tox # Main TouchDesigner component
├── tests/                      # Test code
│   ├── integration/
│   └── unit/
├── .env                        # Local environment variables (git ignored)
├── dotenv                      # Template for .env
└── orval.config.ts             # Orval config (TS client generation)

API 코드 생성 워크플로

이 프로젝트에서는 OpenAPI 기반 코드 생성 도구(Orval/openapi-generator-cli)를 사용합니다.

API 정의: Node.js MCP 서버와 TouchDesigner 내부에서 실행되는 Python 서버 간의 API 계약은 src/api/index.yml 에 정의되어 있습니다.

Python 서버 생성( npm run gen:webserver ):
- Docker를 통해 openapi-generator-cli 사용합니다.
- src/api/index.yml 읽습니다.
- API 정의를 기반으로 Python 서버 스켈레톤( td/modules/td_server/ )을 생성합니다. 이 코드는 TouchDesigner 내부에서 WebServer DAT를 통해 실행됩니다.
- Docker를 설치하고 실행해야 합니다.
Python 핸들러 생성( npm run gen:handlers ):
- 사용자 정의 Node.js 스크립트( td/genHandlers.js )와 Mustache 템플릿( td/templates/ )을 사용합니다.
- 생성된 Python 서버 코드나 OpenAPI 사양을 읽습니다.
- td/modules/mcp/controllers/generated_handlers.py``td/modules/mcp/services/api_service.py generated_handlers.py)을 생성합니다.
TypeScript 클라이언트 생성( npm run gen:mcp ):
- Orval 사용하여 openapi-generator-cli 에 포함된 스키마 YAML에서 도구 검증을 위한 API 클라이언트 코드와 Zod 스키마를 생성합니다.
- Node.js 서버가 WebServer DAT에 요청을 하는 데 사용되는 유형화된 TypeScript 클라이언트( src/tdClient/ )를 생성합니다.

빌드 프로세스( npm run build )는 모든 필수 생성 단계( npm run gen )를 실행한 후 TypeScript 컴파일( tsc )을 실행합니다.

기여하다

여러분의 기여를 환영합니다!

저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
변경 사항을 만드세요
테스트를 추가하고 모든 것이 제대로 작동하는지 확인합니다( npm test )
변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
브랜치에 푸시합니다( git push origin feature/amazing-feature )
풀 리퀘스트 열기

구현 내용을 변경할 때는 항상 적절한 테스트를 포함하세요.

특허

MIT

TouchDesigner MCP

Integrations