simple-salesforce-mcp

가벼운 Salesforce MCP 서버입니다. 런타임 의존성 두 개(mcp, httpx)만으로 stdio를 통해 Salesforce REST API와 직접 통신하며, 샌드박스 환경에는 의존성 트리가 너무 무거운 공식 @salesforce/mcp DX 서버를 대체하는, 콜드 스타트가 빠른 서버로 제작되었습니다.

도구

모든 도구에는 MCP 애너테이션(readOnlyHint / destructiveHint / idempotentHint)이 포함됩니다. update_record와 delete_record는 호출에 confirm: true가 포함되지 않으면 실행을 거부하며, 거부 메시지는 모델이 사용자에게 정확한 변경 사항을 제시하고 먼저 승인을 받도록 안내합니다. SOQL 자체는 데이터를 수정할 수 없으므로 탈출구는 읽기 전용으로 유지됩니다.

Related MCP server: Salesforce MCP Server

인증

서버는 OAuth 흐름을 자체적으로 수행하지 않습니다. 기존 액세스 토큰을 사용하며, 토큰은 매 도구 호출 시마다 다시 읽힙니다(따라서 외부 프로세스가 언제든 토큰을 교체할 수 있습니다).

1. Salesforce CLI 인증 저장소($HOME 아래):

   • ~/.sf/config.json → {"target-org": "<username>"} (또는 레거시 ~/.sfdx/sfdx-config.json → {"defaultusername": ...})

   • ~/.sfdx/<username>.json → {"accessToken": "...", "instanceUrl": "https://..."}

   이 형식은 sf org login이 기록하는 형식이며, JustParent 플랫폼이 샌드박스에 생성해 주는 형식입니다(플랫폼은 각 호출 전에 액세스 토큰을 갱신합니다). 이 파일들의 리프레시 토큰과 클라이언트 시크릿은 무시됩니다 — 메모리로 읽히거나 저장되거나 로깅되지 않습니다.

2. 환경 변수(로컬/독립 실행용 대체 수단): SALESFORCE_ACCESS_TOKEN 및 SALESFORCE_INSTANCE_URL.

토큰이 거부되면(HTTP 401 / INVALID_SESSION_ID) 서버는 인증 저장소를 한 번 다시 읽고 재시도한 후, 연결을 다시 수립해야 한다고 보고합니다.

REST API 버전의 기본값은 62.0이며, SALESFORCE_API_VERSION으로 재정의할 수 있습니다.

실행

# Standalone with env vars (get a token via: sf org display --json)
SALESFORCE_ACCESS_TOKEN=... \
SALESFORCE_INSTANCE_URL=https://yourorg.my.salesforce.com \
uvx --from git+https://github.com/JustParent/simple-salesforce-mcp simple-salesforce-mcp

Claude Desktop / 일반 MCP 클라이언트 설정:

{
  "mcpServers": {
    "salesforce": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/JustParent/simple-salesforce-mcp", "simple-salesforce-mcp"],
      "env": {
        "SALESFORCE_ACCESS_TOKEN": "...",
        "SALESFORCE_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      }
    }
  }
}

스모크 테스트(네트워크 없이 버전, 자격 증명 상태, 도구를 출력하고 0으로 종료):

uvx --from . simple-salesforce-mcp --test

개발

uv run pytest                    # unit tests, no network needed
uv run ruff check .              # lint
uv run ruff format .             # format (--check to verify only)
uv run mypy                      # type check (src and tests)
uv run simple-salesforce-mcp --test
npx @modelcontextprotocol/inspector uv run simple-salesforce-mcp   # interactive

CI(.github/workflows/tests.yml)는 모든 푸시와 풀 리퀘스트에서 실행됩니다. Python 3.10–3.13에서 테스트 스위트를 실행하고, ruff 린트·포맷 검사와 mypy를 수행하며, 샌드박스와 동일한 방식(uvx --from .)으로 패키지를 설치하여 패키징 문제를 잡아내는 패키징 작업도 포함합니다.

보안 참고 사항

• 액세스 토큰 전용: 서버는 리프레시 토큰을 요청하거나 읽거나 저장하지 않습니다.

• 파괴적 작업(update/delete)은 명시적인 confirm=true 인자가 있어야만 실행되며, 모델이 먼저 사용자 승인을 받도록 안내합니다.

• SOQL 페이지네이션 커서(next_url)는 /services/data/... 경로인지 검증되며, 객체/레코드 식별자는 URL에 포함되기 전에 검증됩니다.

• 응답에는 크기 상한이 적용되며 명시적인 잘림(truncation) 알림이 포함됩니다.