使用说明

维基mcp

管理Confluence维基页面的模型上下文协议（MCP）服务器。

Streamable HTTP Transport支持 -使用MCP标准HTTP通信方式。

🚀 功能

浏览页面（wiki_get_page)
生成页面（wiki_create_page)
修改页面（wiki_update_page)
删除页面（wiki_delete_page)
搜索页面（wiki_search)
浏览空间列表（wiki_get_spaces)

📋 要求

Python 3.10+
Docker（使用容器时）
Confluence Server/Data Center或Confluence Cloud

🔧 设置环境变量

Confluence连接设置

方法1:断开IP和端口（建议） 🌟

环境变量	必需	默认值	说明	示例
`CONFLUENCE_HOST`	✅	`localhost`	Confluence服务器IP/域	`192.168.1.100`
`CONFLUENCE_PORT`	❌	`8090`	Confluence服务器端口	`8090`
`CONFLUENCE_PROTOCOL`	❌	`http`	协议	`http` / `https`

方法2:输入完整URL

环境变量	必需	默认值	说明	示例
`CONFLUENCE_URL`	ENT--Confluence完整URL	`http://192.168.1.100:8090`

💡 优先级: CONFLUENCE_URL > CONFLUENCE_HOST + CONFLUENCE_PORT

认证设置

环境变量	必需	默认值	说明	示例
`CONFLUENCE_PERSONAL_TOKEN`	✅	-	个人访问令牌（服务器/DC용)	`OTEzNjg...`
`CONFLUENCE_USERNAME`	-	用户名（适用于Cloud）	`user@company.com`
`CONFLUENCE_API_TOKEN`	--API令牌（用于云） `ATATT3x...`
`CONFLUENCE_SSL_VERIFY`	❌	`true`	验证SSL证书	`true` / `false`

认证方式：

服务器/DC: CONFLUENCE_PERSONAL_TOKEN 必需
云： CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN 必需

MCP服务器设置

环境变量	必需	默认值	说明	示例
`MCP_TRANSPORT`	❌	`streamable`	通信方式	`streamable` / `stdio`
`MCP_HOST`	❌	`0.0.0.0`	侦听IP（允许外部连接）	`0.0.0.0` / `192.168.1.200`
`MCP_PORT`	❌	`8002`	服务端口	`8002` / `8080`

💡 通信方式：

streamable：HTTP Streamable Transport（推荐）-标准MCP HTTP通信
stdio：标准I/O方式

💡 MCP_HOST设置：

0.0.0.0：允许所有网络接口连接（建议）
127.0.0.1：仅允许localhost连接
192.168.1.200：仅从特定IP进行监听（增强安全性）

🐳 使用Docker

1映像构建

cd mcp-wiki
docker build -t wiki-mcp:latest .

运行2⃣容器

本地测试（localhost:8090）

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_HOST="host.docker.internal" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

💡 Docker 桌面版在中 host.docker.internal通过访问主机。

输入IP和端口分离（建议） 🌟

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_HOST="192.168.1.100" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

输入完整URL

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_URL="http://192.168.1.100:8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

使用HTTPS

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_PROTOCOL="https" \
  -e CONFLUENCE_HOST="wiki.company.com" \
  -e CONFLUENCE_PORT="443" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

使用环境文件（.env）

# .env 파일 생성
cat > .env << EOF
CONFLUENCE_HOST=192.168.1.100
CONFLUENCE_PORT=8090
CONFLUENCE_PROTOCOL=http
CONFLUENCE_PERSONAL_TOKEN=your-token-here
MCP_PORT=8002
EOF

# 실행
docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  --env-file .env \
  wiki-mcp:latest

3检查日志

docker logs -f wiki-mcp-server

4停止/删除容器

docker stop wiki-mcp-server
docker rm wiki-mcp-server

📦 部署封闭网络

保存1 ENT⃣图像

docker save wiki-mcp:latest -o wiki-mcp-image.tar

文件传输到2⃣封闭网络

wiki-mcp-image.tar 将文件复制到封闭网络服务器

加载并运行3⃣映像

# 이미지 로드
docker load -i wiki-mcp-image.tar

# 폐쇄망 A 실행
docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_HOST="192.168.1.100" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="폐쇄망A-토큰" \
  wiki-mcp:latest

# 폐쇄망 B 실행 (IP만 다름)
docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_HOST="10.0.0.50" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="폐쇄망B-토큰" \
  wiki-mcp:latest

💡 封闭网络部署技巧

典型情况（标准端口）

# 환경마다 IP만 변경
# 폐쇄망 A
-e CONFLUENCE_HOST="192.168.1.100"

# 폐쇄망 B
-e CONFLUENCE_HOST="10.20.30.40"

# 폐쇄망 C
-e CONFLUENCE_HOST="172.16.0.10"

💡 端口使用默认值（8090）

特殊情况（非标准端口）

# 포트가 다른 경우
-e CONFLUENCE_HOST="192.168.1.100"
-e CONFLUENCE_PORT="9090"

需要更改的项目

项目	因环境而异	示例
✅ 汇流成本	IP地址	`192.168.1.100`
✅ 汇流_个人_令牌	代币（安全）	`OTEzNjg...`
⚠️ 汇流口	仅当端口为非标准端口时	`9090`

不需要更改的项目

项目	默认值	原因
❌ MCP端口	`8002`	标准端口
❌ MCP_HOST	`0.0.0.0`	标准设置
❌ 汇流口	`8090`	Confluence默认端口
❌ 汇流协议	`http`	封闭网络通常是HTTP

💻 本地开发

1安装依赖性

# uv 설치 (Windows PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 프로젝트 의존성 설치
cd mcp-wiki
uv sync

设置2⃣环境变量

# .env 파일 생성
cat > .env << EOF
CONFLUENCE_HOST=localhost
CONFLUENCE_PORT=8090
CONFLUENCE_PERSONAL_TOKEN=your-token-here
EOF

运行3⃣

# Streamable HTTP 모드 (권장)
uv run wiki-mcp --transport streamable --port 8002

# 또는 환경 변수 사용
export MCP_PORT=8002
uv run wiki-mcp

# STDIO 모드
uv run wiki-mcp --transport stdio

🔌 Cursor IDE集成

1️⃣ `mcp.json` 设置

本地环境（wiki-mcp在同一台PC上运行）

Cursor设置文件（C:\Users\<username>\.cursor\mcp.json）：

{
  "mcpServers": {
    "wiki-mcp": {
      "url": "http://localhost:8002/mcp/"
    }
  }
}

远程服务器环境（wiki-mcp在其他服务器上运行）

{
  "mcpServers": {
    "wiki-mcp": {
      "url": "http://192.168.1.200:8002/mcp/"
    }
  }
}

💡 端点信息：

MCP端点： /mcp/
健康检查： /health
服务器信息： /info

💡 192.168.1.200请更改为wiki-mcp服务器的实际IP地址。

重新启动2⃣Cursor

完全退出并重新启动Cursor时，将自动连接。

3使用示例

wiki-mcp로 TES 스페이스의 페이지 목록 알려줘

wiki-mcp로 페이지 ID 98371 내용 가져와줘

🖥️ 远程服务器部署

场景：在单独的服务器上运行wiki-mcp

在1⃣服务器上运行

# 서버 192.168.1.200에서 실행
docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e MCP_HOST="0.0.0.0" \
  -e MCP_PORT="8002" \
  -e CONFLUENCE_HOST="192.168.1.100" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="토큰" \
  wiki-mcp:latest

环境变量说明：

MCP_HOST="0.0.0.0"：启用外部连接
MCP_PORT="8002"：服务端口
CONFLUENCE_HOST：Confluence服务器IP
CONFLUENCE_PORT：Confluence服务器端口

2防火墙设置

# Linux (firewalld)
sudo firewall-cmd --add-port=8002/tcp --permanent
sudo firewall-cmd --reload

# Windows
New-NetFirewallRule -DisplayName "wiki-mcp" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow

3客户机PC连接

mcp.json:

{
  "mcpServers": {
    "wiki-mcp": {
      "url": "http://192.168.1.200:8002/mcp/"
    }
  }
}

网络配置

PC A (Cursor)
    │
    │ HTTP Streamable (MCP Protocol)
    ▼
서버 B (192.168.1.200)
    wiki-mcp:8002 (FastAPI + MCP SDK)
    │
    │ REST API (requests)
    ▼
서버 C (192.168.1.100)
    Confluence:8090

🔑 创建Personal Access Token

汇流服务器/数据中心

Confluence登录
配置文件图标→ 设置
左侧菜单→ 个人访问令牌
创建令牌 单击
输入名称后创建
复制生成的令牌（无法再次查看！）

🛠️ 故障排除

1⃣“未设置Confluence URL”

# 방법 1: HOST와 PORT 설정
export CONFLUENCE_HOST="192.168.1.100"
export CONFLUENCE_PORT="8090"

# 방법 2: 전체 URL 설정
export CONFLUENCE_URL="http://192.168.1.100:8090"

2⃣“未设置身份验证信息”

# Server/DC
export CONFLUENCE_PERSONAL_TOKEN="your-token"

# Cloud
export CONFLUENCE_USERNAME="user@email.com"
export CONFLUENCE_API_TOKEN="your-api-token"

3 SSL证书错误

export CONFLUENCE_SSL_VERIFY=false

4集装箱无法启动

# 로그 확인
docker logs wiki-mcp-server

# 환경 변수 확인
docker exec wiki-mcp-server env | grep CONFLUENCE

📚 环境变量优先级

URL解析顺序：

直接作为参数传递的 url （最优先）
环境变量 CONFLUENCE_URL （完整URL）
环境变量 CONFLUENCE_HOST + CONFLUENCE_PORT + CONFLUENCE_PROTOCOL （组合）

🏗️ 技术堆栈

版本0.2.0（Streamable HTTP）

区分技术用途 |------|------|------| | MCP传输 |MCP SDK流式HTTP |流式HTTP통신 | | Web框架 | Starlette | HTTP服务器| | ASGI服务器 运行Uvicorn|异步服务器| | 汇流API |requests|Confluence REST API调用（同步）| | 异步处理 | asyncio.to_thread（）|在异步环境中运行同步代码|

主要更改（v0.1.0→v0.2.0）

更改的部分

MCP传输上海证券交易所→ 可流式传输的HTTP （标准MCP协议）
库：fastmcp→ mcp+Starlette
端点: /sse → /mcp/
通信方式：服务器发送的事件→ HTTP流式传输

维持的部分

Confluence API客户端 (api_client.py：未更改
数据模型 (models.py：未更改
所有功能：页面CRUD，搜索，空间查询相同
环境变量：相同的Confluence设置
部署Docker：可用的方式相同

🎯 优点

遵循MCP标准协议
更好的兼容性和可扩展性
通过异步处理提高性能
提供RESTful API端点（/health, /)

📄 许可证

该项目可用于个人和商业用途。