mma-mcp

Chinese / 中文版

로컬 Wolfram Engine을 래핑하여 AI 어시스턴트(Claude, ChatGPT 등)가 Wolfram Language를 통해 기호 수학, 수치 해석 및 데이터 시각화를 수행할 수 있도록 하는 Model Context Protocol (MCP) 서버입니다.

면책 조항: 이 프로젝트는 비공식적이고 독립적인 개인 프로젝트입니다. Wolfram Research, Inc.와 제휴, 후원, 보증 또는 인증을 받지 않았습니다. "Wolfram", "Wolfram Language", "Wolfram Engine", "Mathematica" 및 관련 마크는 Wolfram Research의 상표입니다.

이 소프트웨어에는 Wolfram Engine / Mathematica 바이너리, 활성화 키, 라이선스 파일 또는 기타 독점 자료가 포함되어 있지 않습니다. 사용자는 Wolfram의 라이선스 약관에 따라 자신의 Wolfram Engine 또는 Mathematica 사본을 독립적으로 획득하고 적절하게 라이선스를 취득해야 합니다.

이 프로젝트의 유일한 목적은 라이선스를 보유한 개인이 자신의 라이선스 범위 내에서 자신의 컴퓨터에 로컬로 설치된 Wolfram 커널을 AI 어시스턴트를 통해 호출할 수 있도록 하는 것입니다. 제3자에게 Wolfram Engine 액세스를 재배포하는 것은 의도된 사용 사례가 아니며 Wolfram의 라이선스 약관을 위반할 수 있습니다.

기능

• MCP 도구: evaluate (텍스트) 및 evaluate_image (PNG, 실험적) — 두 가지 범용 도구를 통한 모든 Wolfram Language 기능

• 전송: stdio (로컬) 및 스트리밍 가능한 HTTP

• 보안: 블랙리스트/화이트리스트 모드 및 29개의 기능 그룹을 갖춘 커널 이전 표현식 필터링

• 클라이언트 RBAC: 클라이언트별 자격 증명, 역할별 도구 및 보안 정책 제어 — 동일한 컴퓨터에서 서로 다른 AI 클라이언트를 격리하기 위함

• OAuth 2.1: 웹 기반 MCP 클라이언트(Claude.ai, ChatGPT)를 위한 인증 서버

• 구성 기반: 단일 TOML 파일로 모든 동작 제어

사전 요구 사항

• Python 3.11+

• Wolfram Engine 또는 Mathematica (적절한 라이선스 보유)

• uv 패키지 관리자

빠른 시작

# Clone and install
git clone https://github.com/siqiliu-tsinghua/mma-mcp.git
cd mma-mcp
uv sync

# Graphics export dependencies (headless servers only — desktops already have these)
sudo apt-get install -y libfontconfig1 libgl1 libasound2t64 libxkbcommon0 libegl1

# Generate default config
uv run mma-mcp init

# Generate security group files (requires Wolfram kernel, ~1 min)
uv run mma-mcp setup

# Start server (stdio, for local MCP clients)
uv run mma-mcp serve

클라이언트 구성

Claude Code / VS Code (stdio)

.mcp.json에 추가:

{
  "mcpServers": {
    "mma-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/mma-mcp", "run", "mma-mcp"]
    }
  }
}

Claude Desktop (stdio)

claude_desktop_config.json에 추가 (설정 -> 개발자 -> 구성 편집):

{
  "mcpServers": {
    "mma-mcp": {
      "command": "/path/to/mma-mcp/.venv/bin/mma-mcp"
    }
  }
}

macOS/Linux의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json 또는 ~/.config/Claude/claude_desktop_config.json에서 구성을 찾으십시오.

HTTP 전송

uv run mma-mcp serve --transport http --host 127.0.0.1 --port 8000

구성

모든 설정은 mma_mcp.toml (또는 [tool.mma-mcp] 하위의 pyproject.toml)에 있습니다.

uv run mma-mcp init  # generates mma_mcp.toml with comments

주요 섹션:

보안

표현식은 Wolfram 커널에 도달하기 전에 필터링됩니다. 기호는 정규식을 통해 추출되며 활성 정책에 따라 확인됩니다.

블랙리스트 모드 (기본값): 위험한 그룹(system_exec, 파일 I/O, 네트워킹, 동적 평가)을 차단합니다.

화이트리스트 모드: 명시적으로 활성화된 그룹의 기호만 허용합니다.

29개의 기능 그룹(22개의 안전한 그룹 + 7개의 위험한 그룹)이 약 6000개의 Wolfram Language 기호를 다룹니다. 로컬 커널에서 다시 생성하십시오:

uv run mma-mcp setup          # required after cloning (generates from your local kernel)
uv run mma-mcp setup --force   # force regeneration (e.g., after Wolfram Engine upgrade)

클라이언트 ID 및 역할

HTTP 전송을 사용할 때 클라이언트별 자격 증명 및 역할을 구성하여 동일한 커널에 연결하는 서로 다른 AI 클라이언트(예: Claude 및 ChatGPT)를 격리할 수 있습니다:

# Generate password hash
uv run mma-mcp hash-password

# Generate TOML snippet for a new client
uv run mma-mcp add-client alice --role admin

각 클라이언트는 액세스할 수 있는 도구, 사용할 수 있는 Wolfram 기호 및 리소스 제한(타임아웃, 결과 크기)을 제어하는 역할에 바인딩됩니다. 동시 클라이언트는 커널 작업자 풀을 통해 격리됩니다. 각 도구 호출은 임시 WL 컨텍스트가 있는 전용 커널 프로세스에서 실행됩니다.

구성 세부 정보는 mma_mcp.toml의 [auth] 섹션을 참조하십시오.

개발

# Run tests
uv run pytest tests/ -v

# Inspect MCP tools interactively
uv run mcp dev src/mma_mcp/server.py

CLI 명령

클라이언트 호환성

라이선스

MIT — 이 저장소의 코드에만 적용됩니다. Wolfram Engine / Mathematica의 사용은 Wolfram Research의 자체 라이선스 약관에 따릅니다.