Skip to main content
Glama
conred-lin

jiandaoyun-mcp

by conred-lin
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

简道云 MCP 服务

基于 FastMCP 3.x，通过 SSE 协议将简道云表单操作封装为 9 个 MCP Tools，供 Claude Code 或其他 MCP 客户端调用。

特性

  • API Key 一次配置，处处生效 — 在客户端连接时通过 Authorization header 传入，后续调用自动携带，无需每次传参

  • 9 个 Tools — 覆盖应用发现 → 表单探索 → 数据读写全流程

  • Docker 一键部署 — 开箱即用，易于自托管

  • HTTPS 支持 — 提供 Nginx 反向代理配置示例

Related MCP server: mdymcp

目录结构

jiandaoyun-mcp/
├── server.py              # MCP 主服务（含 ApiKeyMiddleware）
├── client.py              # 简道云 HTTP 客户端封装
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── nginx/
│   └── jiandaoyun-mcp.conf    # Nginx 反向代理示例配置
└── README.md

快速开始

前置条件

  • Docker（推荐）或 Python 3.12+

  • 简道云账号及 API Key（在简道云后台「设置」→「API 管理」获取）

1. 克隆仓库

git clone https://github.com/your-username/jiandaoyun-mcp.git
cd jiandaoyun-mcp

2. 启动服务

方式一：Docker（推荐）

docker compose up -d --build

服务默认绑定在 127.0.0.1:8765，仅本机可访问。

方式二：直接运行（Python 3.12+）

pip install -r requirements.txt
python server.py

3. 验证服务

curl -i http://localhost:8765/sse
# 期望响应：HTTP/1.1 200 OK，Content-Type: text/event-stream

4. 配置 MCP 客户端

Claude Code CLI：

claude mcp add --transport sse jiandaoyun http://localhost:8765/sse \
  --header "Authorization: Bearer <your_api_key>"

手动编辑 ~/.claude.json：

{
  "mcpServers": {
    "jiandaoyun": {
      "type": "sse",
      "url": "http://localhost:8765/sse",
      "headers": {
        "Authorization": "Bearer <your_api_key>"
      }
    }
  }
}

配置完成后重启 Claude Code 即可使用。

远程部署（公网 / 局域网）

如需将服务部署在远程服务器供多端共用，推荐用 Nginx

开放端口绑定（跳过 Nginx 时）

将 docker-compose.yml 中的端口绑定改为监听所有网卡：

ports:
  - "0.0.0.0:8765:8765"

然后客户端使用 http://<server-ip>:8765/sse 连接（明文，仅内网推荐）。

配置 Nginx HTTPS（推荐用于公网）

  1. 将 nginx/jiandaoyun-mcp.conf 复制到 /etc/nginx/conf.d/

  2. 按注释修改以下三项：

    占位符

    说明

    your.domain.com

    你的域名

    /path/to/your/cert.crt

    SSL 证书路径

    /path/to/your/cert.key

    SSL 私钥路径

  3. 重载 Nginx：

    nginx -t && nginx -s reload

  4. 客户端连接地址改为：

    claude mcp add --transport sse jiandaoyun https://your.domain.com:9444/sse \
  --header "Authorization: Bearer <your_api_key>"

SSE 关键配置说明（已写入模板，勿删）：

配置项

说明

proxy_buffering off

禁用响应缓冲，保证事件实时推送

proxy_cache off

禁用缓存

proxy_read_timeout 86400

超时设为 24h，维持长连接

proxy_set_header Connection ""

关闭 keep-alive 改写

测试用自签名证书

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout cert.key -out cert.crt \
  -subj "/CN=localhost"

API Key 传递方式

服务端支持以下三种方式（优先级从高到低）：

优先级

方式

1

Authorization: Bearer <key> header（推荐）

2

X-Api-Key: <key> header

3

?api_key=<key> query 参数（仅 SSE 握手请求有效）

可用 Tools（共 9 个）

推荐使用流程

list_apps → list_forms → get_form_fields → 读写操作

先了解有哪些应用和表单，再获取字段结构（字段 name、label、type），最后进行数据操作。

应用 / 表单发现

list_apps — 列出所有应用

limit:  100    # 可选，每页返回数量，默认 100
skip:   0      # 可选，跳过条数，用于分页

返回：apps[]，每项包含 app_id、name

list_forms — 列出应用下所有表单

app_id: "5e3b1234abcd5678ef901234"

返回：forms[]，每项包含 entry_id、name

get_form_fields — 获取表单字段结构

app_id:   "5e3b1234abcd5678ef901234"
entry_id: "5e3b5678abcd1234ef901234"

返回：widgets[]，每项包含 name（字段 ID，如 _widget_1234）、label（显示名）、type

常见字段类型： text（单行文本）、textarea（多行文本）、number（数字）、datetime（日期时间）、combo（下拉框）、radio（单选）、checkbox（多选）

数据读取

get_record — 查询单条记录

app_id:   "5e3b..."
entry_id: "5e3b..."
data_id:  "66a1234567890abc12345678"    # 记录的 _id 字段

query_records — 查询多条记录

基础用法：

app_id:   "5e3b..."
entry_id: "5e3b..."
limit:    100
fields:   ["_widget_xxx", "_widget_yyy"]    # 可选，指定返回字段

简单筛选（filters）— 精确匹配：

filters: {"_widget_xxx": "张三", "_widget_yyy": "已完成"}

复杂筛选（filter）— 支持 gt/lt/like/range 等：

filter: {
  "rel": "and",
  "cond": [
    {"field": "_widget_xxx", "type": "gt",   "value": ["100"]},
    {"field": "_widget_yyy", "type": "like", "value": ["张"]}
  ]
}

filter 和 filters 同时传入时，filter 优先生效。

翻页（游标分页）：

# 第一页
query_records(app_id=..., entry_id=..., limit=100)

# 取最后一条记录的 _id，作为下一页的 data_id
query_records(app_id=..., entry_id=..., limit=100, data_id="上一页最后一条的_id")

数据写入

data 字段格式

data = {
    "_widget_1234567890ab": {"value": "文本内容"},    # 文本字段
    "_widget_abcdef123456": {"value": 123},            # 数字字段
    "_widget_fedcba654321": {"value": "2024-06-01"},   # 日期字段
}

字段的 name（如 _widget_1234）通过 get_form_fields 获取。

create_record — 新建单条记录

app_id:       "5e3b..."
entry_id:     "5e3b..."
data:         {...}
data_creator: "username"    # 可选，指定创建者用户名

返回：{"data": {"_id": "新记录ID", ...}}

create_records_batch — 批量新建（≤ 100 条）

app_id:    "5e3b..."
entry_id:  "5e3b..."
data_list: [
  {"_widget_xxx": {"value": "第一条"}},
  {"_widget_xxx": {"value": "第二条"}}
]

返回：{"status": "success", "success_count": 2, "success_ids": ["id1", "id2"]}

update_record — 修改单条记录

只需传入需要修改的字段，未传字段保持原值。

app_id:   "5e3b..."
entry_id: "5e3b..."
data_id:  "66a1234567890abc12345678"
data:     {"_widget_xxx": {"value": "修改后的值"}}

delete_record — 删除单条记录

⚠️ 删除不可恢复，请谨慎操作。

app_id:   "5e3b..."
entry_id: "5e3b..."
data_id:  "66a1234567890abc12345678"

返回：{"status": "success"}

修改默认端口

服务默认使用 8765。如需修改：

  1. docker-compose.yml — 修改 ports 中的宿主机端口映射

  2. server.py 末尾 — 修改 mcp.run(port=8765) 中的值

运维命令

# 查看服务状态
docker compose ps

# 实时查看日志
docker compose logs -f

# 重启服务
docker compose restart

# 更新代码后重新部署
docker compose up -d --build

# 停止并移除容器
docker compose down

技术架构

MCP 客户端（Claude Code 等）
      ↓  SSE（HTTP 或 HTTPS）
  [可选] Nginx 反向代理（SSL 终止）
      ↓  HTTP 127.0.0.1:8765
Docker 容器（python:3.12-slim）
      ↓
FastMCP 3.x + Uvicorn
      ↓  HTTPS
简道云 API (www.jiandaoyun.com/api/v5/...)

组件

版本

FastMCP

≥ 2.0.0（已测试 3.x）

Python

3.12

传输协议

SSE (Server-Sent Events)

简道云 API

v5

License

MIT

This server cannot be installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/conred-lin/jiandaoyun-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server