# OpenCode MCP Servers 安裝指南

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-24 |
| 文件版本 | V1.1 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-24 | 創建文件 | OpenCode | OpenCode / big-pickle |
| V1.1 | 2026-03-24 | 新增 sentry, context7, playwright MCP | OpenCode | OpenCode / big-pickle |

---

## 概述

本文檔說明如何在 macOS 上為 OpenCode 安裝和配置 MCP (Model Context Protocol) Servers，透過標準化的協定讓 AI 助手能夠存取各種外部服務和工具。

MCP Servers 提供：
- 標準化的工具調用介面
- 安全的資源存取控制
- 統一的配置和管理方式

---

## 已安裝的 MCP Servers

| Server | 安裝方式 | 用途 | 狀態 |
|--------|----------|------|------|
| gitea | Homebrew | Gitea API 操作 | ✅ |
| n8n | NPM (@nextoolsolutions/mcp-n8n) | n8n Workflow 管理 | ✅ |
| postgres | NPM (@modelcontextprotocol/server-postgres) | PostgreSQL 資料庫查詢 | ✅ |
| redis | NPM (@modelcontextprotocol/server-redis) | Redis 快取操作 | ✅ |
| mongodb | NPM (mongodb-mcp-server) | MongoDB 文件資料庫 | ✅ |
| qdrant | Python (qdrant/mcp-server-qdrant) | Qdrant 向量搜尋 | ✅ |
| filesystem | NPM (@modelcontextprotocol/server-filesystem) | 檔案系統操作 | ✅ |
| sentry | NPM (@sentry/mcp-server) | 錯誤追蹤和監控 | ⏳ |
| context7 | NPM (@upstash/context7-mcp) | 技術文檔搜尋 | ✅ |
| playwright | NPM (@playwright/mcp) | 瀏覽器自動化 | ✅ |

---

## 前置條件

- OpenCode 已安裝
- Node.js (用於 NPM 套件)
- Python 3.11+ (用於 qdrant-mcp)
- 相關服務已運行 (PostgreSQL, Redis, Qdrant, Gitea, n8n, MongoDB)

---

## 安裝步驟

### Step 1: 安裝 NPM MCP Servers

```bash
npm install -g @modelcontextprotocol/server-postgres
npm install -g @modelcontextprotocol/server-redis
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-everything
npm install -g @nextoolsolutions/mcp-n8n
npm install -g mongodb-mcp-server
npm install -g @sentry/mcp-server
npm install -g @upstash/context7-mcp
npm install -g @playwright/mcp
```

**驗證**:

```bash
which mcp-server-postgres
which mcp-server-redis
which mcp-server-filesystem
which mcp-n8n
which mongodb-mcp-server
which sentry-mcp
which context7-mcp
which playwright-mcp
```

---

### Step 2: 安裝 gitea-mcp-server

```bash
brew install gitea-mcp-server
```

**驗證**:

```bash
which gitea-mcp-server
```

---

### Step 3: 安裝 MongoDB MCP Server (已包含在 Step 1)

MongoDB MCP 已透過 NPM 安裝：

```bash
npm install -g mongodb-mcp-server
```

---

### Step 4: 安裝 Qdrant MCP Server (Python)

```bash
cd /tmp
git clone https://github.com/qdrant/mcp-server-qdrant.git
cd mcp-server-qdrant
/opt/homebrew/bin/python3.11 -m pip install -e .
```

**驗證**:

```bash
which mcp-server-qdrant
```

---

### Step 5: 配置 OpenCode MCP 設定

編輯 `~/.config/opencode/opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gitea": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/gitea-mcp-server",
        "-token",
        "<GITEA_TOKEN>",
        "-host",
        "http://localhost:3000"
      ]
    },
    "n8n": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-n8n"],
      "environment": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "<N8N_API_KEY>"
      }
    },
    "postgres": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/mcp-server-postgres",
        "postgresql://accusys:accusys@localhost:5432/momentry"
      ]
    },
    "redis": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/mcp-server-redis",
        "redis://:accusys@localhost:6379"
      ]
    },
    "mongodb": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mongodb-mcp-server"],
      "environment": {
        "MONGODB_URI": "mongodb://localhost:27017"
      }
    },
    "qdrant": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-server-qdrant"],
      "environment": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": ""
      }
    },
    "filesystem": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/mcp-server-filesystem",
        "/Users/accusys/momentry"
      ]
    },
    "sentry": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/sentry-mcp",
        "--access-token",
        "<SENTRY_ACCESS_TOKEN>"
      ]
    },
    "context7": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/context7-mcp"]
    },
    "playwright": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/playwright-mcp"]
    }
  }
}
```

---

### Step 6: 驗證 MCP Servers

```bash
# 列出所有 MCP servers
opencode mcp ls

# 或在 OpenCode 中執行
/mcps
```

---

## MCP Server 工具說明

### gitea

| 工具 | 說明 |
|------|------|
| list_repos | 列出倉庫 |
| get_repo | 取得倉庫詳情 |
| list_issues | 列出 Issues |
| create_issue | 建立 Issue |
| list_pulls | 列出 Pull Requests |

---

### n8n (43 個工具)

#### Workflows (10)
| 工具 | 說明 |
|------|------|
| n8n_list_workflows | 列出所有 workflows |
| n8n_get_workflow | 取得 workflow 詳情 |
| n8n_create_workflow | 建立新 workflow |
| n8n_update_workflow | 更新 workflow |
| n8n_delete_workflow | 刪除 workflow |
| n8n_activate_workflow | 啟用 workflow |
| n8n_deactivate_workflow | 停用 workflow |
| n8n_execute_workflow | 執行 workflow |
| n8n_get_workflow_tags | 取得 workflow 標籤 |
| n8n_update_workflow_tags | 更新 workflow 標籤 |

#### Executions (3)
| 工具 | 說明 |
|------|------|
| n8n_list_executions | 列出執行記錄 |
| n8n_get_execution | 取得執行詳情 |
| n8n_delete_execution | 刪除執行記錄 |

#### Data Tables (8)
| 工具 | 說明 |
|------|------|
| n8n_list_datatables | 列出資料表 |
| n8n_create_datatable | 建立資料表 |
| n8n_get_datatable | 取得資料表結構 |
| n8n_get_datatable_rows | 取得資料表列 |
| n8n_insert_datatable_rows | 插入資料列 |
| n8n_update_datatable_rows | 更新資料列 |
| n8n_upsert_datatable_row | 插入或更新資料列 |
| n8n_delete_datatable_rows | 刪除資料列 |

#### Tags (5)
| 工具 | 說明 |
|------|------|
| n8n_list_tags | 列出所有標籤 |
| n8n_get_tag | 取得標籤 |
| n8n_create_tag | 建立標籤 |
| n8n_update_tag | 更新標籤 |
| n8n_delete_tag | 刪除標籤 |

#### 其他 (17)
| 工具 | 說明 |
|------|------|
| n8n_list_credentials | 列出憑證 |
| n8n_create_credential | 建立憑證 |
| n8n_delete_credential | 刪除憑證 |
| n8n_get_credential_schema | 取得憑證 schema |
| n8n_list_users | 列出使用者 |
| n8n_get_user | 取得使用者 |
| n8n_delete_user | 刪除使用者 |
| n8n_list_variables | 列出變數 |
| n8n_create_variable | 建立變數 |
| n8n_delete_variable | 刪除變數 |
| n8n_list_projects | 列出專案 |
| n8n_create_project | 建立專案 |
| n8n_update_project | 更新專案 |
| n8n_delete_project | 刪除專案 |
| n8n_generate_audit | 產生安全審計報告 |
| n8n_health_check | 健康檢查 |
| n8n_trigger_webhook | 觸發 webhook |

---

### postgres

| 工具 | 說明 |
|------|------|
| query | 執行唯讀 SQL 查詢 |

**範例**:

```json
{
  "sql": "SELECT * FROM users LIMIT 10;"
}
```

---

### redis

| 工具 | 說明 |
|------|------|
| set | 設定 key-value 配對 |
| get | 取得 key 的值 |
| delete | 刪除 key(s) |
| list | 列出符合模式的 keys |

---

### mongodb

| 工具 | 說明 |
|------|------|
| mongodb_list_databases | 列出所有資料庫 |
| mongodb_list_collections | 列出資料庫中的集合 |
| mongodb_find | 查詢文件 |
| mongodb_insert_one | 插入單個文件 |
| mongodb_insert_many | 插入多個文件 |
| mongodb_update_one | 更新單個文件 |
| mongodb_update_many | 更新多個文件 |
| mongodb_delete_one | 刪除單個文件 |
| mongodb_delete_many | 刪除多個文件 |
| mongodb_aggregate | 聚合查詢 |

**範例**:

```json
{
  "database": "momentry",
  "collection": "videos",
  "filter": {"uuid": "abc123"}
}
```

---

### qdrant

| 工具 | 說明 |
|------|------|
| 查詢工具 | 向量搜尋和集合管理 |

---

### filesystem

| 工具 | 說明 |
|------|------|
| read_file | 讀取檔案 |
| write_file | 寫入檔案 |
| list_directory | 列出目錄 |
| create_directory | 建立目錄 |

---

### sentry

| 工具 | 說明 |
|------|------|
| sentry_list_issues | 列出 issues |
| sentry_get_issue | 取得 issue 詳情 |
| sentry_create_issue | 建立 issue |
| sentry_update_issue | 更新 issue |
| sentry_list_projects | 列出專案 |
| sentry_search_docs | 搜尋 Sentry 文件 |

**注意**: 需要設定 `SENTRY_ACCESS_TOKEN`

**取得 Token**:
1. 登入 https://sentry.io
2. Settings → Developer Tools → API Keys
3. 建立新 Token (需要 `event:read`, `project:read` 權限)

---

### context7

| 工具 | 說明 |
|------|------|
| context7_resolve-library-id | 解析函式庫 ID |
| context7_query-docs | 查詢函式庫文件 |

**用途**: 即時技術文件和函式庫查詢，獲取最新的 API 語法和範例。

---

### playwright

| 工具 | 說明 |
|------|------|
| playwright_navigate | 導航到 URL |
| playwright_screenshot | 截圖 |
| playwright_click | 點擊元素 |
| playwright_type | 輸入文字 |
| playwright_evaluate | 執行 JavaScript |

**用途**: 瀏覽器自動化測試、網頁截圖、網頁內容抓取。

---

## 管理指令

### 新增 MCP Server

```bash
opencode mcp add
```

### 列出 MCP Servers

```bash
opencode mcp ls
```

### 認證 OAuth Server

```bash
opencode mcp auth <server-name>
```

---

## 故障排除

### MCP Server 連線失敗

1. 檢查服務是否運行：
   ```bash
   # PostgreSQL
   pg_isready -h localhost -p 5432

   # Redis
   redis-cli -a accusys ping

   # Qdrant
   curl -s http://localhost:6333/
   ```

2. 檢查 MCP Server 是否安裝：
   ```bash
   which mcp-server-postgres
   which mcp-server-redis
   ```

3. 驗證配置格式正確

---

### Token 或 API Key 無效

1. PostgreSQL: 確認使用者名稱和密碼
2. Redis: 確認密碼
3. n8n: 確認 API Key 未過期
4. Gitea: 確認 Token 有效

---

## 檔案位置

| 類型 | 路徑 | 說明 |
|------|------|------|
| OpenCode 配置 | ~/.config/opencode/opencode.json | MCP 設定檔 |
| Gitea MCP | /opt/homebrew/bin/gitea-mcp-server | 安裝路徑 |
| n8n MCP | /opt/homebrew/bin/mcp-n8n | 安裝路徑 |
| Postgres MCP | /opt/homebrew/bin/mcp-server-postgres | 安裝路徑 |
| Redis MCP | /opt/homebrew/bin/mcp-server-redis | 安裝路徑 |
| Qdrant MCP | /opt/homebrew/bin/mcp-server-qdrant | 安裝路徑 |
| Filesystem MCP | /opt/homebrew/bin/mcp-server-filesystem | 安裝路徑 |

---

## 常用指令

```bash
# 列出所有 MCP servers
opencode mcp ls

# 測試 PostgreSQL MCP
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"query","arguments":{"sql":"SELECT 1;"}}}' | \
  /opt/homebrew/bin/mcp-server-postgres postgresql://accusys:accusys@localhost:5432/momentry

# 測試 Redis MCP
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ping","arguments":{}}}' | \
  /opt/homebrew/bin/mcp-server-redis redis://:accusys@localhost:6379
```

---

## 版本資訊

- 版本: 1.0
- 安裝日期: 2026-03-24
- 文件更新: 2026-03-24

---

## 相關文件

- [OpenCode Guide](./OPENCODE_GUIDE.md) - OpenCode 使用指南
- [Gitea MCP 安裝](./INSTALL_GITEA_MCP.md) - Gitea MCP 詳細設定
- [n8n MCP 設定](./N8N_MCP_SETUP.md) - n8n MCP 詳細設定
- [服務總覽](./SERVICES.md) - 所有服務狀態總覽