> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NoimosAI MCP 서버

> Claude, ChatGPT, Cursor 등 MCP 호환 클라이언트에서 NoimosAI를 직접 사용합니다.

## 개요

NoimosAI MCP 서버는 [Model Context Protocol](https://modelcontextprotocol.io)을 통해 NoimosAI 작업공간을 노출합니다. 연결이 완료되면 MCP 호환 클라이언트에서 NoimosAI 에이전트와 대화하고, 작업공간과 연동을 조회하며, 소셜 게시물을 클라이언트 안에서 바로 발행할 수 있습니다.

연결 방법은 두 가지입니다.

* **Remote MCP (권장)** — `https://mcp.noimosai.com/mcp`에 호스팅. 브라우저 OAuth, 설치 없음, 사용자 본인으로 동작합니다.
* **Local MCP (`@agos-labs/noimosai-mcp`)** — npm으로 로컬에서 서버 실행. 헤드리스 / API 키 흐름에 적합합니다.

<Tabs>
  <Tab title="Remote (권장)">
    Endpoint: `https://mcp.noimosai.com/mcp`

    ### 요구 사항

    * NoimosAI 계정 (로그인 상태)
    * Remote MCP / Custom Connectors를 지원하는 클라이언트

    ### 권한 부여

    클라이언트가 스스로 등록한 뒤 브라우저가 열려 NoimosAI 로그인과 `mcp:tools` 스코프 동의를 진행합니다. 동의 후 액세스 토큰이 발급되며 도구 호출은 사용자 본인으로 실행됩니다.

    ### 연결

    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --scope local --transport http noimos https://mcp.noimosai.com/mcp
        ```

        세션 내에서 `/mcp`를 실행하고 브라우저에서 동의를 완료한 뒤 Claude Code로 돌아옵니다.
      </Tab>

      <Tab title="Claude.ai / Desktop">
        Settings → Connectors → **Add custom connector** → URL을 `https://mcp.noimosai.com/mcp`로 설정 → 브라우저에서 로그인 후 동의.
      </Tab>

      <Tab title="ChatGPT Web">
        URL `https://mcp.noimosai.com/mcp`로 Custom MCP connector를 추가한 뒤 동의를 완료합니다. ChatGPT는 일반 `search` / `fetch` 도구를 자동 인식하지 않으므로 NoimosAI 도구는 이름으로 직접 호출하세요.
      </Tab>
    </Tabs>

    ### 참고

    * `post`는 항상 먼저 `dryRun: true`로 호출하여 페이로드를 확인하세요. `dryRun`을 지정하지 않으면 실제 소셜 계정에 게시됩니다.
    * 연결을 끊으려면 클라이언트에서 connector를 제거합니다.

    ### 문제 해결

    * **동의 화면이 열리지 않음** — connector를 제거하고 다시 추가합니다.
    * **도구가 표시되지 않음** — `mcp:tools` 스코프가 부여되었는지, 계정에 작업공간이 하나 이상 있는지 확인합니다.
    * **토큰 만료** — 클라이언트에서 다시 권한을 부여합니다.
  </Tab>

  <Tab title="Local (npm)">
    npm에 [`@agos-labs/noimosai-mcp`](https://www.npmjs.com/package/@agos-labs/noimosai-mcp)로 배포됩니다. 클라이언트의 자식 프로세스로 실행됩니다.

    ### 요구 사항

    * Node.js `>= 18`
    * MCP 호환 클라이언트 (Claude Desktop, Cursor, VS Code, …)
    * 팀 설정에서 발급한 NoimosAI API 키

    ### 설정

    `your-api-key`와 `your-workspace-id`는 NoimosAI 팀 설정 값으로 바꾸세요.

    <Tabs>
      <Tab title="Claude Desktop">
        `claude_desktop_config.json`에 추가:

        ```json theme={null}
        {
          "mcpServers": {
            "noimosai": {
              "command": "npx",
              "args": ["-y", "@agos-labs/noimosai-mcp"],
              "env": {
                "NOIMOS_API_KEY": "your-api-key",
                "NOIMOS_WORKSPACE_ID": "your-workspace-id"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cursor">
        `.cursor/mcp.json`에 추가:

        ```json theme={null}
        {
          "mcpServers": {
            "noimosai": {
              "command": "npx",
              "args": ["-y", "@agos-labs/noimosai-mcp"],
              "env": {
                "NOIMOS_API_KEY": "your-api-key",
                "NOIMOS_WORKSPACE_ID": "your-workspace-id"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="VS Code">
        `.vscode/mcp.json`에 추가:

        ```json theme={null}
        {
          "servers": {
            "noimosai": {
              "command": "npx",
              "args": ["-y", "@agos-labs/noimosai-mcp"],
              "env": {
                "NOIMOS_API_KEY": "your-api-key",
                "NOIMOS_WORKSPACE_ID": "your-workspace-id"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    설정을 변경한 뒤에는 MCP 서버가 반영되도록 클라이언트를 재시작하세요.

    ### 환경 변수

    | 변수                    | 필수  | 설명                                           |
    | --------------------- | --- | -------------------------------------------- |
    | `NOIMOS_API_KEY`      | 예   | NoimosAI API 키 (팀 설정의 API 탭에서 발급).           |
    | `NOIMOS_WORKSPACE_ID` | 아니요 | 도구 호출에서 `workspaceId`를 생략할 때 사용할 기본 작업공간 ID. |
  </Tab>
</Tabs>

## 도구

두 전송 방식 모두 동일한 도구를 제공합니다.

### `chat`

NoimosAI 에이전트에 메시지를 보냅니다. 에이전트 응답과 추출된 소셜 게시물을 담은 구조화된 NoimosPostJson을 반환합니다. 마케팅 분석, 소셜 게시물 작성, SEO, 콘텐츠 생성에 적합합니다.

| 매개변수          | 타입       | 필수  | 설명                                                             |
| ------------- | -------- | --- | -------------------------------------------------------------- |
| `prompt`      | `string` | 예   | 에이전트에 보낼 메시지 또는 지시.                                            |
| `workspaceId` | `string` | 아니요 | 작업공간 ID. 기본값은 `NOIMOS_WORKSPACE_ID`(Local) 또는 인증된 계정의 기본 작업공간. |
| `sessionId`   | `string` | 아니요 | 기존 대화를 이어갈 세션 ID. 생략하면 새 세션이 생성됩니다.                            |

### `list_workspaces`

사용 가능한 작업공간의 ID와 이름을 조회합니다. 매개변수 없음.

### `list_integrations`

작업공간에 연결된 연동(소셜 미디어 계정)을 조회합니다. 반환된 `providerAccountId`는 `post` 도구의 각 항목에서 필요합니다.

### `post`

소셜 미디어 게시물을 발행합니다. `chat`이 반환하는 NoimosPostJson 형식의 게시물 데이터를 받습니다. 각 항목에는 `providerAccountId`(`list_integrations`에서 조회)가 반드시 포함되어야 합니다. 발행 전에는 항상 `dryRun: true`로 페이로드를 확인하세요.

| 매개변수          | 타입        | 필수  | 설명                                                           |
| ------------- | --------- | --- | ------------------------------------------------------------ |
| `posts`       | `array`   | 예   | NoimosPostJson 형식의 게시물 배열. 각 항목에 `providerAccountId`가 필요합니다. |
| `schedule`    | `string`  | 예   | 발행 시각. 즉시는 `"now"`, 예약은 `"YYYY-MM-DD HH:MM"`.                |
| `workspaceId` | `string`  | 아니요 | 작업공간 ID. 기본값은 기본 작업공간.                                       |
| `dryRun`      | `boolean` | 아니요 | `true`이면 실제 발행 없이 전송 내용만 표시합니다. 기본값은 `false`.                |

## 관련 문서

* [NoimosAI란 무엇인가요?](/ko/help-center/getting-started/what-is-noimosai)
* [NoimosAI CLI](/ko/developers/cli/overview)
* [npm 패키지](https://www.npmjs.com/package/@agos-labs/noimosai-mcp)