内容
<!-- Generated by https://github.com/flowgent-labs/mcpfather -->
# confluence-mcp
[](https://go.dev/)
[](https://modelcontextprotocol.io/)
[](https://prometheus.io/)
[](https://opentelemetry.io/)
[](https://openid.net/connect/)
[](https://ldap.com/)
[](https://helm.sh/)
> 企业级MCP服务器，专为AI调用Confluence数据中心API而设计，由MCPFather生成 - 暴露 **176个原生工具**。每个API操作都成为一个AI可调用的工具，具有类型化的模式和自定义的聚合虚拟工具，内置身份验证转发和可观测性，甚至可以作为普通的CLI使用。
## 快速开始
```sh
make
# 或使用OpenTelemetry分布式跟踪（gRPC或HTTP）
make build-with-otel-grpc # OTLP gRPC导出器
make build-with-otel-http # OTLP HTTP/Protobuf导出器
```
### 以 `HTTP` 模式启动（示例）
```sh
# 配置上游API
export MCP__UPSTREAM__ENDPOINT=https://api.example.com
export MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN=your-token
./bin/confluence-mcp --transport http --port 8080 &
```
- 检查MCP前端身份验证（OAuth2.1）。
```bash
export MCP__AUTH__FRONTEND__OIDC__ENABLED=true
export MCP__AUTH__FRONTEND__OIDC__ISSUER="https://keycloak.example.com/realms/master"
export MCP__AUTH__FRONTEND__OIDC__AUDIENCE="confluence-mcp"
./bin/confluence-mcp -v 10 --transport http --port 8080
# 获取OAuth2.1元数据。
curl -s https://iam.example.com/realms/master/.well-known/openid-configuration
curl -s localhost:8080/.well-known/oauth-protected-resource
#{"resource":"confluence-mcp","authorization_servers":["https://keycloak.example.com/realms/master"],"bearer_methods_supported":["header"]}
```
### 以 `CLI` 模式运行（示例）
```sh
./bin/confluence-mcp -v 1 -t cli list
./bin/confluence-mcp -v 1 -t cli <tool-name> [OPTIONS]
```
## 选项
| 参数 | 默认值 | 描述 |
|------|---------|-------------|
| `-t, --transport` | `stdio` | `stdio` / `http` / `cli` |
| `-p, --port` | `8080` | HTTP服务器端口 |
| `--metrics-port` | `0` | 覆盖管理端口（0 = 使用配置） |
| `-v, --verbose` | `0` | 日志详细程度（0–10） |
| `--print-default-config` | — | 将默认的config.yaml打印到stdout |
## 身份验证
身份验证分为两个独立的层 - 两者之间不共享凭证：
| 层 | 配置文件路径 | 环境变量前缀 | 角色 |
|---|---|---|---|
| **前端** | `auth.frontend.oidc` | `MCP__AUTH__FRONTEND__OIDC__*` | 验证AI代理的承载令牌（入站） |
| **后端OIDC** | `auth.backend.oidc` | `MCP__AUTH__BACKEND__OIDC__*` | 服务器自己的OIDC客户端凭证，用于上游API |
| **后端LDAP** | `auth.backend.ldap` | `MCP__AUTH__BACKEND__LDAP__*` | 服务器自己的LDAP服务帐户绑定，用于上游API |
| **后端静态** | `auth.backend.static` | `MCP__AUTH__BACKEND__STATIC__*` | 服务器自己的静态令牌/cookie，用于上游API |
**前端（入站）** - 验证AI代理呈现的承载令牌。仅适用于 `--transport http` ；stdio没有网络边界。按照RFC 9728 / MCP身份验证规范进行标准OIDC JWT承载令牌验证。
**后端（出站）** - 服务器用于调用上游API的凭证。令牌优先级（第一个可用的优先） :
1. **OIDC** 客户端凭证授权 (`auth.backend.oidc.*`)
2. **LDAP** 服务帐户绑定 (`auth.backend.ldap.*`)
3. **静态** 承载令牌 (`auth.backend.static.bearer_token`)
AI代理的入站令牌 **永远不会** 被转发到上游（MCP规范：令牌传通禁止）。
还可以通过 `auth.backend.static.cookie_token` 提供基于cookie的身份验证。
## 配置
创建 `~/.confluence-mcp/config.yaml` （运行 `--print-default-config` 获取完整模板）：
```yaml
upstream:
endpoint: "" # 上游API基准URL（例如 https://api.example.com）
# 当为true时，MCP会话ID被转发为X-MCP-Session-ID头。
enable_mcp_session_forward: true
runtime:
download_dir: ""
log_authorization: false
# ---- 身份验证 ----
# frontend = 入站：验证MCP客户端（AI代理）呈现的承载令牌。
# backend = 出站：服务器用于调用上游API的凭证。
# 两者是独立的 - 入站令牌永远不会被重复用于出站
# （参见MCP身份验证规范：令牌传通禁止）。
auth:
frontend:
# 标准OAuth 2.1 / OIDC JWT承载令牌验证（资源服务器角色，RFC 9728）。
# 仅在http传输中强制执行；stdio没有网络边界。
oidc:
enabled: false
issuer: "" # 例如 https://idp.example.com/realms/myrealm
jwks_uri: "" # 可选覆盖（如果为空，则从发行者自动发现）
audience: "" # 预期的JWT "aud"声明；也作为RFC 9728受保护的资源标识符发布
# 当为true时，验证的前端JWT声明（sub, email）被转发到上游
# 为X-MCP-Client-Token-Sub和X-MCP-Client-Token-Email头。
enable_client_token_claim_forward: true
# 附加的JWT声明转发为X-MCP-Client-Token-<Header-Name>头。
# 例如 ["given_name", "family_name", "preferred_username"]
# additional_client_token_claim_forward: []
# 出站：服务器用于调用上游API的凭证。
backend:
oidc:
enabled: true
issuer: https://idp.example.com/realms/myrealm
client_id: my-client
client_secret: "${MCP__AUTH__BACKEND__OIDC__CLIENT_SECRET}"
scopes: openid
# token_url: "" # 从发行者 /.well-known 自动发现
ldap:
enabled: false
url: ldaps://ldap.example.com
base_dn: dc=example,dc=com
bind_dn: cn=svc,dc=example,dc=com
bind_password: "${MCP__AUTH__BACKEND__LDAP__BIND_PASSWORD}"
static:
bearer_token: "${MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN}" # 或设置cookie_token
nativeTools:
expose:
register_all_tools_by_default: true # 暴露所有原生工具
# includes: [Tool1, Tool2] # 或白名单特定工具
# excludes: [Tool3] # 隐藏噪音工具
```
所有值都可以通过 `MCP__` 前缀的环境变量设置（例如 `MCP__AUTH__BACKEND__OIDC__CLIENT_ID` ）。
## 管理 - 指标、跟踪、Pprof
```yaml
mgmt:
enabled: true
host: 0.0.0.0
port: 9991
otel:
enabled: false
endpoint: localhost:4317
protocol: grpc
sample_rate: 1.0
metrics:
enabled: true
prometheus: true
export_interval: 30s
pprof:
enabled: false
server_bind: 0.0.0.0:6669
```
```sh
./bin/confluence-mcp --transport http --port 8080
curl http://localhost:9991/metrics # Prometheus端点
curl http://localhost:9991/health # 健康检查
```
跟踪跨度命名为 `mcp.tool.<name>` 。W3C `traceparent` 被传播到上游调用。
## 可用工具（176个）
| 工具 | 描述 |
|------|-------------|
| `Add` | 将类别添加到空间 - 将类别添加到给定 {@link Space} 的描述中，由spaceKey标识。示例请求URI将空间类别'testCategory'添加到空间，空间键为TEST： `https://example.com/confluence/rest/api/space/TEST/category/testCategory` |
| `AddContentWatcher` | 添加内容监视器 - 为给定的用户和内容ID创建新的监视器。用户可选。如果未指定，则使用当前登录的用户。否则，可以通过用户密钥或用户名指定。当指定用户与登录用户不同时，登录用户必须是Confluence管理员。示例请求URI： `http://example.com/confluence/rest/api/user/watch/content/131213` `http://example.com/confluence/rest/api/user/watch/content/131213?username=jblogs` `http://example.com/confluence/rest/api/user/watch/content/131213?key=ff8080815a58e24c015a58e263710000` |
| `AddLabels` | 添加标签 - 将标签列表添加到指定的内容中。主体是列表的json表示。 |
| `AddSpaceWatch` | 添加空间监视器 - 为给定的用户和空间键创建新的监视器。用户可选。如果未指定，则使用当前登录的用户。否则，可以通过用户密钥或用户名指定。当指定用户与登录用户不同时，登录用户必须是Confluence管理员。示例请求URI： `http://example.com/confluence/rest/api/user/watch/space/SPACEKEY` `http://example.com/confluence/rest/api/user/watch/space/SPACEKEY?username=jblogs` `http://example.com/confluence/rest/api/user/watch/space/SPACEKEY?key=ff8080815a58e24c015a58e263710000` `http://example.com/confluence/rest/api/user/watch/space/SPACEKEY?contentType=blogpost` |
| `Archive` | 存档空间 - 存档给定的Space，由spaceKey标识。此方法幂等，即如果空间已经存档，则不会采取任何操作。 |
| `ByOperation` | 获取按操作的所有限制 - 返回按操作的所有限制信息。 |
| `CancelAllQueuedJobs` | 取消所有排队的作业 - 取消所有排队的作业。不会影响当前正在处理的作业。 |
| `CancelJob` | 取消作业 - 取消作业。如果作业已经取消或失败，该方法将执行无操作。 |
| `ChangePassword` | 更改密码 - 更改用户名标识的用户密码。 **验证规则**： - 新密码不应为空或空白。 |
| `ChangePassword1` | 更改密码 - 更改当前用户的密码。 验证规则： - 新密码不应为空或空白 示例请求URI： `http://example.com/confluence/rest/api/user/current/password` |
| `Children` | 获取内容的子项 - 返回内容直接子项的映射。内容可以有多种类型子项。例如，页面可以有子项，它们也是页面，但它也可以有评论和附件。 子项返回的类型由请求中的 `expand` 查询参数指定。该参数可以包括多个子项类型。如果未在 `expand` 参数中包含任何类型，则返回的映射将仅列出可扩展的子项类型，对于 `id` 路径参数引用的内容。 |
| `ChildrenOfType` | 获取内容类型子项 - 返回内容直接子项的映射，限制为单个子项类型。子项返回的类型由请求中的"type"路径参数指定。 |
| `CommentsOfContent` | 获取内容评论 - 返回内容评论。示例请求URI： - `http://example.com/confluence/rest/api/content/1234/child/comment` - `http://example.com/confluence/rest/api/content/1234/child/comment?expand=body.view` - `http://example.com/confluence/rest/api/content/1234/child/comment?start=20&limit=10` - `http://example.com/confluence/rest/api/content/1234/child/comment?location=footer&location=inline&location=resolved` - `http://example.com/confluence/rest/api/content/1234/child/comment?expand=extensions.inlineProperties,extensions.resolution` |
| `Contents` | 获取空间内容 - 返回给定空间的内容。 示例请求URI： `http://example.com/confluence/rest/api/space/TEST/content?expand=history` |
| `ContentsWithType` | 获取空间垃圾内容 - 返回给定空间的垃圾内容。 示例请求URI： `http://example.com/confluence/rest/api/space/TEST/trash?limit=100&cursor=content:false:612345` |
| … | *161个工具未显示* |
## 虚拟工具
通过声明式管道DSL组合原生工具：
```yaml
virtualTools:
- name: MyVirtualTool
description: 链多个原生工具
inputSchema:
type: object
properties:
appId: { type: string }
required: [appId]
pipeline:
- id: getApp
kind: call
spec: { tool: GetApplication, args: { applicationId: "$input.appId" } }
- id: appName
kind: jq
spec: { from: "$getApp", expr: .name }
- id: done
kind: return
spec: { from: "$appName" : jq
spec: { from: "$getApp", expr: ".name" }
- id: done
kind: return
spec: { from: "$appName" }
```
管道种类：`call`、`jq`、`foreach`、`emit`、`return`。
## 代理集成
### OpenCode
- `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"confluence-mcp": {
"type": "local",
"command": ["bash", "-c", "/path/to/confluence-mcp"],
"args": ["--transport", "stdio"],
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
},
"enabled": true
}
}
}
```
### Claude 代码
- `~/.claude.json`:
```json
{
"mcpServers": {
"confluence-mcp": {
"command": "/path/to/confluence-mcp",
"args": ["--transport", "stdio"],
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### Codex CLI
- `~/.codex/config.toml`:
```toml
[mcp_servers.confluence-mcp]
url = "http://localhost:8080/mcp"
bearer_token_env_var = "MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN"
```
### Cursor
- `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"confluence-mcp": {
"command": "/path/to/confluence-mcp",
"args": ["--transport", "stdio"],
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### OpenCode（远程）
- `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"confluence-mcp": {
"type": "remote",
"url": "http://localhost:8080/mcp",
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### Claude 代码（远程）
- `~/.claude.json` （用户MCP）：
```json
{
"mcpServers": {
"confluence-mcp": {
"url": "http://localhost:8080/mcp",
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### Codex CLI（远程）
- `~/.codex/config.toml`:
```toml
[mcp_servers.confluence-mcp]
url = "http://localhost:8080/mcp"
bearer_token_env_var = "MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN"
```
### Cursor（远程）
- `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"confluence-mcp": {
"url": "http://localhost:8080/mcp"
}
}
}
```
## 部署 - Docker
### 构建
```sh
make build-image
```
或手动：
```sh
docker build -t ghcr.io/<YOUR_ORG>/confluence-mcp:latest -f deploy/docker/Dockerfile .
docker push ghcr.io/<YOUR_ORG>/confluence-mcp:latest
```
### 运行
从GitHub容器注册表拉取预构建的镜像：
```sh
docker pull ghcr.io/<YOUR_ORG>/confluence-mcp:latest
```
首先生成默认配置，然后在运行时挂载：
```sh
docker run --rm ghcr.io/<YOUR_ORG>/confluence-mcp:latest --print-default-config > ~/.confluence-mcp/config.yaml
```
- **静态承载令牌**
```sh
docker run -d --name confluence-mcp \
-p 8080:8080 -p 9991:9991 \
-e MCP__UPSTREAM__ENDPOINT="https://api.example.com" \
-e MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN="YOUR_BEARER_TOKEN" \
-v ~/.confluence-mcp:/home/mcp/.confluence-mcp \
ghcr.io/<YOUR_ORG>/confluence-mcp:latest \
--transport http --port 8080
```
- **OIDC后端身份验证**
```sh
docker run -d --name confluence-mcp \
-p 8080:8080 -p 9991:9991 \
-e MCP__UPSTREAM__ENDPOINT="https://api.example.com" \
-e MCP__AUTH__BACKEND__OIDC__ENABLED=true \
-e MCP__AUTH__BACKEND__OIDC__ISSUER="https://idp.example.com/realms/myrealm" \
-e MCP__AUTH__BACKEND__OIDC__CLIENT_ID="my-client" \
-e MCP__AUTH__BACKEND__OIDC__CLIENT_SECRET="YOUR_CLIENT_SECRET" \
-v ~/.confluence-mcp:/home/mcp/.confluence-mcp \
ghcr.io/<YOUR_ORG>/confluence-mcp:latest \
--transport http --port 8080
```
- **LDAP后端身份验证**
```sh
docker run -d --name confluence-mcp \
-p 8080:8080 -p 9991:9991 \
-e MCP__UPSTREAM__ENDPOINT="https://api.example.com" \
-e MCP__AUTH__BACKEND__LDAP__ENABLED=true \
-e MCP__AUTH__BACKEND__LDAP__URL="ldaps://ldap.example.com" \
-e MCP__AUTH__BACKEND__LDAP__BASE_DN="dc=example,dc=com" \
-e MCP__AUTH__BACKEND__LDAP__BIND_DN="cn=svc,dc=example,dc=com" \
-e MCP__AUTH__BACKEND__LDAP__BIND_PASSWORD="YOUR_BIND_PASSWORD" \
-v ~/.confluence-mcp:/home/mcp/.confluence-mcp \
ghcr.io/<YOUR_ORG>/confluence-mcp:latest \
--transport http --port 8080
```
### 使用mcpclient.sh测试
容器启动后，使用捆绑的`mcpclient.sh`进行验证。
> **注意：** `mcpclient.sh`仅支持**后端静态**令牌身份验证。如果服务器需要
> **前端OIDC/LDAP**身份验证，请改用真正的AI代理MCP客户端。
```sh
# 指向映射的主机端口（包括/mcp路径）
export MCP_SERVER_ENDPOINT=http://localhost:18080/mcp
# 调用任意工具（示例：Add）
./mcpclient.sh call '{"<参数>":"<值>"}'
```
# 列出所有可用工具
./mcpclient.sh list-tools
```
> **提示：** 映射主机配置文件目录以实现持久化配置：
> `-v ~/.confluence-mcp:/home/mcp/.confluence-mcp`
## 部署 — Kubernetes (Helm)
首先生成默认配置，然后在运行时挂载：
```sh
docker run --rm ghcr.io/<YOUR_ORG>/confluence-mcp:latest --print-default-config > ~/.confluence-mcp/config.yaml
```
- **静态 bearer token**
```sh
helm upgrade -i confluence-mcp deploy/helm \
--set image.repository=ghcr.io/<YOUR_ORG>/confluence-mcp \
--set image.tag=latest \
--set secret.static.create=true \
--set secret.static.bearerToken="YOUR_BEARER_TOKEN" \
--set config.upstream.endpoint="https://api.example.com"
```
- **OIDC 身份验证**
```sh
helm upgrade -i confluence-mcp deploy/helm \
--set image.repository=ghcr.io/<YOUR_ORG>/confluence-mcp \
--set image.tag=latest \
--set secret.static.create=true \
--set secret.static.oidcClientSecret="YOUR_OIDC_CLIENT_SECRET" \
--set config.auth.backend.oidc.enabled=true \
--set config.auth.backend.oidc.issuer="https://idp.example.com" \
--set config.auth.backend.oidc.clientId="my-client" \
--set config.upstream.endpoint="https://api.example.com"
```
- **LDAP 身份验证**
```sh
helm upgrade -i confluence-mcp deploy/helm \
--set image.repository=ghcr.io/<YOUR_ORG>/confluence-mcp \
--set image.tag=latest \
--set secret.static.create=true \
--set secret.static.ldapBindPassword="YOUR_LDAP_BIND_PASSWORD" \
--set config.auth.backend.ldap.enabled=true \
--set config.auth.backend.ldap.url="ldaps://ldap.example.com" \
--set config.auth.backend.ldap.bindDN="cn=svc,dc=example,dc=com" \
--set config.upstream.endpoint="https://api.example.com"
```
请参阅 `deploy/helm/values.yaml` 以获取所有可配置参数。
## 贡献
我们欢迎贡献！以下是您可以帮助的方式：
1. **Fork** 仓库并创建功能分支
2. **进行更改** — 添加功能、修复错误或改进文档
3. **添加测试** — 每个新功能或错误修复都应包含单元测试
4. **运行测试套件** — `make test` 必须通过且无回归
5. **提交拉取请求** — 描述您所更改的内容及原因
### 开发设置
```sh
git clone https://github.com/<YOUR_ORG>/confluence-mcp.git
cd confluence-mcp
make build
make test
```
### 代码风格
- 遵循标准 Go 惯例（`go fmt`、`go vet`）
- 保持函数小且专注
- 编写清晰的提交消息
请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取详细指南和我们的 [行为准则](CODE_OF_CONDUCT.md)。
## 许可证
该项目根据 MIT 许可证授权 — 请参阅 [LICENSE](LICENSE) 文件以获取详细信息。
## 联系
如有疑问、建议或支持：
- **GitHub 问题：** [创建一个问题](../../confluence-mcp/issues)
- **讨论：** [开始讨论](../../confluence-mcp/discussions)
- **电子邮件：** <jameswong1376@gmail.com>
## 致谢
该 MCP 服务器由 [MCPFather](https://github.com/flowgent-labs/mcpfather) 生成，一款企业级 OpenAPI-to-MCP 代码生成器。
使用以下优秀的开源项目构建：
- [mcp-go](https://github.com/mark3labs/mcp-go) — 模型上下文协议的 Go SDK
- [OpenTelemetry](https://opentelemetry.io/) — 指标和跟踪的可观察性框架
- [Prometheus](https://prometheus.io/) — 指标收集和警报
- [Viper](https://github.com/spf13/viper) — Go 配置管理
- [go-jq](https://github.com/itchyny/gojq) — jq 的纯 Go 实现
- [Keycloak](https://www.keycloak.org/) — 开源身份和访问管理
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器