* 目次 [#ne5c8e39]
#contents
** はじめに [#j21296fb]
* Windows上でOpenCode + MCP連携環境構築 - 実際のハマりポイントと解決法 [#g092fef1]
** はじめに [#m093de59]
WindowsでOpenCodeを使ってMCP（Model Context Protocol）連携環境を構築しようとした際、いくつかの設定エラーで躓きました。本記事では、実際に遭遇したトラブルシューティングを中心に、Windows環境でのOpenCode + MCP設定手順を解説します。
** なぜOpenCodeが良いのか [#y0ef13be]
*** Claude Codeとの比較 [#vd038617]
WSL不要: Windows上で直接動作
MCP設定の再利用: 既存のMCP設定をほぼそのまま利用可能
環境変数共有: Windows環境変数をそのまま参照
tmux不要: Windows CMD/PowerShellで直接利用可能
** なぜOpenCodeが良いのか [#n0fd8c6c]
*** 従来の課題 [#c5910ed9]
*** Claude Codeとの比較 [#lc0e3443]
- **WSL不要**: Windows上で直接動作
- **MCP設定の再利用**: 既存のMCP設定をほぼそのまま利用可能
- **環境変数共有**: Windows環境変数をそのまま参照
- **tmux不要**: Windows CMD/PowerShellで直接利用可能
Claude CodeはWSL環境が必要
WSL上でMCPサーバーを再設定する必要
環境変数の設定が複雑
ファイルパスの変換が必要
*** 従来の課題 [#l6f50a0f]
- Claude CodeはWSL環境が必要
- WSL上でMCPサーバーを再設定する必要
- 環境変数の設定が複雑
- ファイルパスの変換が必要
** 環境構築手順 [#zc59f407]
*** 前提条件の確認 [#n022db51]
**** Go言語のインストール確認 [#y9dabaee]
** 環境構築手順 [#aa69966f]
*** 前提条件の確認 [#o87e6993]
**** Go言語のインストール確認 [#i8ba0105]
OpenCodeはGo言語で作成されているため、まずGo環境を確認します。
Go言語がインストール済みかチェック
go version
インストールされていない場合
winget install GoLang.Go
パス確認（重要）
echo $GOPATH
echo $GOROOT
**** 環境変数の事前設定 [#d9d63677]
MINGW64環境で設定
export ANTHROPIC_API_KEY_MULTI_AGENT="sk-ant-api03-xxxxx"
設定確認
echo $ANTHROPIC_API_KEY_MULTI_AGENT
*** OpenCodeインストール [#n238155d]
**** インストール手順 [#a89a1d18]
OpenCodeをインストール
go install github.com/opencode-ai/opencode@latest
インストール確認
opencode -v
パスが通っていない場合
export PATH=$PATH:$(go env GOPATH)/bin
*** 設定ファイルでの失敗パターン集 [#i070ae8f]
**** パターン1: JSON構文エラー [#v3af6b19]
失敗例: Windowsパスのエスケープエラー
{
"mcpServers": {
"filesystem": {
"args": ["C:\Users\kh\Desktop"] // エラー！
}
}
}
エラーメッセージ: invalid character 'o' in string escape code
修正方法: スラッシュ記法を使用
{
"mcpServers": {
"filesystem": {
"args": ["C:/Users/kh/Desktop"] // 正解
}
}
}
**** パターン2: 環境変数展開エラー [#zfe1c876]
失敗例: シングルクォートHereDocumentの使用
cat > ~/.opencode.json << 'EOF' # シングルクォートでは展開されない
{
"apiKey": "$(echo $ANTHROPIC_API_KEY_MULTI_AGENT)" # 文字列として扱われる
}
EOF
修正方法: シングルクォートを除去
cat > ~/.opencode.json << EOF # 環境変数が実際に展開される
{
"apiKey": "$(echo $ANTHROPIC_API_KEY_MULTI_AGENT)"
}
EOF
**** パターン3: MCP環境変数設定エラー [#v018c86b]
失敗例: オブジェクト形式での設定
"env": {
"QDRANT_URL": "http://localhost:6333"
}
エラーメッセージ: expected type 'string', got unconvertible type 'map[string]interface'
修正方法: 配列形式を使用
"env": [
"QDRANT_URL=http://localhost:6333"
]
*** 動作確認済み設定ファイル [#oab3a2e5]
# Go言語がインストール済みかチェック
go version
# インストールされていない場合
winget install GoLang.Go
# パス確認（重要）
echo $GOPATH
echo $GOROOT
**** 環境変数の事前設定 [#a2d6bd51]
# MINGW64環境で設定
export ANTHROPIC_API_KEY_MULTI_AGENT="sk-ant-api03-xxxxx"
# 設定確認
echo $ANTHROPIC_API_KEY_MULTI_AGENT
*** OpenCodeインストール [#ea9b0b1f]
**** インストール手順 [#bc44b076]
# OpenCodeをインストール
go install github.com/opencode-ai/opencode@latest
# インストール確認
opencode -v
# パスが通っていない場合
export PATH=$PATH:$(go env GOPATH)/bin
*** 設定ファイルでの失敗パターン集 [#lca6348b]
**** パターン1: JSON構文エラー [#hfaec2c4]
**失敗例**: Windowsパスのエスケープエラー [#hd57a890]
{
"mcpServers": {
"filesystem": {
"args": ["C:\Users\kh\Desktop"] // エラー！
}
}
}
**エラーメッセージ**: `invalid character 'o' in string escape code` [#w15b9881]
**修正方法**: スラッシュ記法を使用 [#a4cdb5e6]
{
"mcpServers": {
"filesystem": {
"args": ["C:/Users/kh/Desktop"] // 正解
}
}
}
**** パターン2: 環境変数展開エラー [#y14277de]
**失敗例**: シングルクォートHereDocumentの使用 [#q5ba38a4]
cat > ~/.opencode.json << 'EOF' # シングルクォートでは展開されない
{
"apiKey": "$(echo $ANTHROPIC_API_KEY_MULTI_AGENT)" # 文字列として扱われる
}
EOF
**修正方法**: シングルクォートを除去 [#a1ffc8b7]
cat > ~/.opencode.json << EOF # 環境変数が実際に展開される
{
"apiKey": "$(echo $ANTHROPIC_API_KEY_MULTI_AGENT)"
}
EOF
**** パターン3: MCP環境変数設定エラー [#g5c2aa84]
**失敗例**: オブジェクト形式での設定 [#tf20d0fa]
"env": {
"QDRANT_URL": "http://localhost:6333"
}
**エラーメッセージ**: `expected type 'string', got unconvertible type 'map[string]interface'` [#i0590641]
**修正方法**: 配列形式を使用 [#tc04bc2a]
"env": [
"QDRANT_URL=http://localhost:6333"
]
*** 動作確認済み設定ファイル [#d9da7caa]
以下は実際にWindows環境で動作確認できた設定例です：
cat > ~/.opencode.json << EOF
{
"data": {
"directory": ".opencode"
},
"providers": {
"anthropic": {
"apiKey": "$(echo $ANTHROPIC_API_KEY_MULTI_AGENT)",
"disabled": false
}
},
"agents": {
"coder": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000
}
},
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:/Users/kh/Desktop",
"C:/Users/kh/prj/multiagent"
]
},
"qdrant": {
"command": "uvx",
"args": [
"mcp-server-qdrant"
],
"env": [
"QDRANT_URL=http://localhost:6333",
"COLLECTION_NAME=khayashi_knowledge",
"EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2"
]
}
},
"shell": {
"path": "bash",
"args": ["-l"]
},
"autoCompact": true
}
EOF
** 起動とトラブルシューティング [#sda2a84e]
*** 正常起動の確認 [#zba6e5f9]
**** 起動コマンド [#z9cb99bd]
opencode
**** 正常な起動メッセージ [#ye74e674]
2025/06/15 10:06:24 WARN Ripgrep (rg) not found in $PATH. Some features might be limited or slower.
2025/06/15 10:06:24 WARN FZF not found in $PATH. Some features might be limited or slower.
cat > ~/.opencode.json << EOF
{
"data": {
"directory": ".opencode"
},
"providers": {
"anthropic": {
"apiKey": "$(echo $ANTHROPIC_API_KEY_MULTI_AGENT)",
"disabled": false
}
},
"agents": {
"coder": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000
}
},
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:/Users/kh/Desktop",
"C:/Users/kh/prj/multiagent"
]
},
"qdrant": {
"command": "uvx",
"args": [
"mcp-server-qdrant"
],
"env": [
"QDRANT_URL=http://localhost:6333",
"COLLECTION_NAME=khayashi_knowledge",
"EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2"
]
}
},
"shell": {
"path": "bash",
"args": ["-l"]
},
"autoCompact": true
}
EOF
** 起動とトラブルシューティング [#l1dc98f7]
*** 正常起動の確認 [#j782848c]
**** 起動コマンド [#sbb09354]
opencode
**** 正常な起動メッセージ [#mb4f6f31]
2025/06/15 10:06:24 WARN Ripgrep (rg) not found in $PATH. Some features might be limited or slower.
2025/06/15 10:06:24 WARN FZF not found in $PATH. Some features might be limited or slower.
この警告は正常で、基本機能には影響ありません。
**** MCP接続確認 [#pa143289]
**** MCP接続確認 [#wd145e23]
起動後、以下のようなPermission Requiredダイアログが表示されれば、MCP連携が正常に動作しています：
Permission Required
Tool: qdrant qdrant-find
Allow (a) Allow for session (s) Deny (d)
** よくあるエラーと解決方法 [#u79d7542]
*** エラー1: opencode: command not found [#tf576dc1]
原因: Goのbinディレクトリがパスに含まれていない
解決方法:
Go環境確認
go env GOPATH
パス追加
export PATH=$PATH:$(go env GOPATH)/bin
永続化（.bashrcに追記）
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
*** エラー2: failed to read config: While parsing config [#ef9b1d6b]
原因: JSON構文エラー
解決方法:
JSON構文チェック
cat ~/.opencode.json | python -m json.tool
または
cat ~/.opencode.json | jq .
*** エラー3: 401 Unauthorized [#oc6216df]
原因: APIキー認証エラー
解決方法:
環境変数確認
echo $ANTHROPIC_API_KEY_MULTI_AGENT
設定ファイル内でのAPIキー確認
cat ~/.opencode.json | grep apiKey
*** エラー4: 起動が非常に遅い [#v811e988]
原因: MCPサーバーの初期化処理
対策: 正常な動作のため、1-2分程度待機
** 実際の動作結果 [#w6b1a95b]
Permission Required
Tool: qdrant qdrant-find
Allow (a) Allow for session (s) Deny (d)
** よくあるエラーと解決方法 [#vd3d62fd]
*** エラー1: `opencode: command not found` [#jfbd3845]
**原因**: Goのbinディレクトリがパスに含まれていない [#q6f2f31c]
**解決方法**: [#uf5f58e9]
# Go環境確認
go env GOPATH
# パス追加
export PATH=$PATH:$(go env GOPATH)/bin
# 永続化（.bashrcに追記）
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
*** エラー2: `failed to read config: While parsing config` [#s464b1c9]
**原因**: JSON構文エラー [#s0cab86d]
**解決方法**: [#w6c9ff93]
# JSON構文チェック
cat ~/.opencode.json | python -m json.tool
# または
cat ~/.opencode.json | jq .
*** エラー3: `401 Unauthorized` [#v3dad331]
**原因**: APIキー認証エラー [#e7c7bd40]
**解決方法**: [#ha803982]
# 環境変数確認
echo $ANTHROPIC_API_KEY_MULTI_AGENT
# 設定ファイル内でのAPIキー確認
cat ~/.opencode.json | grep apiKey
*** エラー4: 起動が非常に遅い [#m741424b]
**原因**: MCPサーバーの初期化処理 [#m2e0842d]
**対策**: 正常な動作のため、1-2分程度待機 [#tc4d8516]
** 実際の動作結果 [#d5304224]
この設定により、以下が確認できました：
*** 成功した機能 [#wb64379d]
Claude 3.7 Sonnetとの通信
Qdrant長期記憶への接続
ファイルシステムアクセス
基本的なコード生成
*** 成功した機能 [#mbc83a24]
- Claude 3.7 Sonnetとの通信
- Qdrant長期記憶への接続
- ファイルシステムアクセス
- 基本的なコード生成
*** 生成されたファイル例 [#n0424277]
*** 生成されたファイル例 [#q177216a]
実際に以下のファイルが自動生成されました：
scripts/
├── github_init.py # GitHub初期化スクリプト
├── monitor.py # 監視システム
└── tmux_session.py # セッション管理
** まとめ [#n79cc1a7]
*** 成功のポイント [#kd9a602b]
scripts/
├── github_init.py # GitHub初期化スクリプト
├── monitor.py # 監視システム
└── tmux_session.py # セッション管理
Go環境の正しい設定 - PATH設定の確認
JSON設定の注意点 - パス記法と環境変数展開
MCP環境変数形式 - 配列形式での設定
段階的なトラブルシューティング - エラーメッセージの活用
** まとめ [#me6ffd7a]
*** Windows環境での利点 [#u4e00f68]
*** 成功のポイント [#rc91f7c9]
1. **Go環境の正しい設定** - PATH設定の確認
2. **JSON設定の注意点** - パス記法と環境変数展開
3. **MCP環境変数形式** - 配列形式での設定
4. **段階的なトラブルシューティング** - エラーメッセージの活用
WSL不要でネイティブ動作
既存の環境変数をそのまま利用
Claude Codeより設定が簡単
*** Windows環境での利点 [#j65b6fd0]
- WSL不要でネイティブ動作
- 既存の環境変数をそのまま利用
- Claude Codeより設定が簡単
Windows上でのOpenCode + MCP環境構築は、適切な設定を行えば非常にスムーズに動作します。特にJSONの構文エラーと環境変数の扱いに注意すれば、初回でも成功する可能性が高いです。
** 参考リンク [#xa666877]
[[OpenCode公式リポジトリ>https://github.com/opencode-ai/opencode]]
[[MCP Server Registry>https://github.com/modelcontextprotocol/servers]]
[[Anthropic Claude API>https://docs.anthropic.com/]]
[[Qdrant Vector Database>https://qdrant.tech/]]
** 参考リンク [#va7e9dd1]
- [[OpenCode公式リポジトリ>https://github.com/opencode-ai/opencode]]
- [[MCP Server Registry>https://github.com/modelcontextprotocol/servers]]
- [[Anthropic Claude API>https://docs.anthropic.com/]]
- [[Qdrant Vector Database>https://qdrant.tech/]]
