DeepSeek TUI MCP Server 制作指南

Wed, 20 May 2026 00:00:00 +0000

以 ds-balance-mcp 为例，说明如何为 DeepSeek TUI 制作一个 MCP Server。

架构概览

1
2
3
4
5
6
7


DeepSeek TUI (MCP Host) MCP Server (独立进程)
 │ │
 │──── stdin (JSON-RPC) ──────→│
 │ │
 │←──── stdout (JSON-RPC) ──────│
 │ │
 │ python3 /path/to/server.py │

传输层：stdio，每行一个 JSON 对象
协议层：JSON-RPC 2.0
注册层：~/.deepseek/mcp.json

最简实现（3 个步骤）

步骤 1：实现 MCP 协议的核心方法

必须实现三个方法：

方法	作用	何时调用
`initialize`	握手，声明协议版本和能力	Server 启动后立即调用
`tools/list`	列出所有可用工具	Initialize 之后
`tools/call`	执行具体工具	用户触发工具调用时

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


def handle(req):
 mid = req.get("id")
 method = req.get("method")
 params = req.get("params", {})

 # ① 握手 —— 声明能力
 if method == "initialize":
 return {
 "jsonrpc": "2.0", "id": mid,
 "result": {
 "protocolVersion": "2024-11-05",
 "capabilities": {"tools": {}},
 "serverInfo": {"name": "my-server", "version": "1.0.0"}
 }
 }

 # ② 列出工具 —— TUI 会据此生成 mcp_<server>_<tool> 工具
 if method == "tools/list":
 return {
 "jsonrpc": "2.0", "id": mid,
 "result": {
 "tools": [
 {
 "name": "hello",
 "description": "打招呼，返回一句问候",
 "inputSchema": {
 "type": "object",
 "properties": {
 "name": {
 "type": "string",
 "description": "要问候的名字"
 }
 },
 "required": []
 }
 }
 ]
 }
 }

 # ③ 执行工具 —— 核心业务逻辑
 if method == "tools/call":
 tool_name = params.get("name")
 arguments = params.get("arguments", {})

 if tool_name == "hello":
 name = arguments.get("name", "World")
 return {
 "jsonrpc": "2.0", "id": mid,
 "result": {
 "content": [{"type": "text", "text": f"Hello, {name}!"}]
 }
 }

 # 未知工具返回错误
 return {
 "jsonrpc": "2.0", "id": mid,
 "error": {"code": -32601, "message": f"Unknown tool: {tool_name}"}
 }

 # 未知方法返回错误
 return {
 "jsonrpc": "2.0", "id": mid,
 "error": {"code": -32601, "message": f"Unknown method: {method}"}
 }

步骤 2：写 stdio 主循环

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


def main():
 # 可选：启动日志写到 stderr，不污染 stdout
 sys.stderr.write("my-server: ready\n")
 sys.stderr.flush()

 for line in sys.stdin:
 line = line.strip()
 if not line:
 continue
 try:
 req = json.loads(line)
 resp = handle(req)
 if resp is not None:
 sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
 sys.stdout.flush()
 except json.JSONDecodeError:
 continue
 except (BrokenPipeError, EOFError):
 break

核心逻辑：读一行 → 处理 → 写一行。

步骤 3：在 `mcp.json` 中注册

编辑 ~/.deepseek/mcp.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "servers": {
 "my-server": {
 "command": "python3",
 "args": ["/root/my-mcp-server.py"],
 "env": {},
 "enabled": true,
 "enabled_tools": [],
 "disabled_tools": []
 }
 }
}

字段	说明
`command`	启动命令
`args`	命令行参数
`env`	环境变量（可选）
`enabled`	是否启用
`enabled_tools`	白名单（空=全部启用）
`disabled_tools`	黑名单

重启 TUI 后会自动启动 Server 进程，工具名格式为 mcp_<server名>_<工具名>，例如 mcp_my-server_hello。

完整模板

以下是一个带错误处理的完整 Python MCP Server 模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


#!/usr/bin/env python3
"""MCP stdio server 模板"""
import sys
import json

def handle(req):
 mid = req.get("id")
 method = req.get("method")
 params = req.get("params", {})

 # 必须处理的协议方法
 if method == "initialize":
 return {
 "jsonrpc": "2.0", "id": mid,
 "result": {
 "protocolVersion": "2024-11-05",
 "capabilities": {"tools": {}},
 "serverInfo": {"name": "my-server", "version": "1.0.0"}
 }
 }

 if method == "notifications/initialized":
 return None

 if method == "ping":
 return {"jsonrpc": "2.0", "id": mid, "result": {}}

 if method == "tools/list":
 return {
 "jsonrpc": "2.0", "id": mid,
 "result": {
 "tools": [
 {
 "name": "hello",
 "description": "打招呼",
 "inputSchema": {
 "type": "object",
 "properties": {
 "name": {
 "type": "string",
 "description": "名字"
 }
 }
 }
 }
 ]
 }
 }

 if method == "tools/call":
 tool = params.get("name")
 args = params.get("arguments", {})

 if tool == "hello":
 name = args.get("name", "World")
 return {
 "jsonrpc": "2.0", "id": mid,
 "result": {
 "content": [{"type": "text", "text": f"Hello, {name}!"}]
 }
 }

 return {
 "jsonrpc": "2.0", "id": mid,
 "error": {"code": -32601, "message": f"Unknown tool: {tool}"}
 }

 return {
 "jsonrpc": "2.0", "id": mid,
 "error": {"code": -32601, "message": f"Unknown method: {method}"}
 }

def main():
 sys.stderr.write("my-server: ready\n")
 sys.stderr.flush()

 for line in sys.stdin:
 line = line.strip()
 if not line:
 continue
 try:
 req = json.loads(line)
 resp = handle(req)
 if resp is not None:
 sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
 sys.stdout.flush()
 except json.JSONDecodeError:
 continue
 except (BrokenPipeError, EOFError):
 break

if __name__ == "__main__":
 main()

ds-balance-mcp 实战分析

实际部署的 ds-balance-mcp 提供了两个工具：

工具名	功能	实现方式
`check_balance`	查询 DeepSeek API 余额	HTTP GET `api.deepseek.com/user/balance`，从 `config.toml` 读取 API Key
`check_token_usage`	查看当前会话 Token 用量	读取 `~/.deepseek/sessions/` 下最新的 JSON 会话文件

`tools/list` 返回的工具定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "tools": [
 {
 "name": "check_balance",
 "description": "查询 DeepSeek API 账户余额（单位：CNY）",
 "inputSchema": {"type": "object", "properties": {}}
 },
 {
 "name": "check_token_usage",
 "description": "查看当前会话的 Token 用量、费用和模型信息",
 "inputSchema": {"type": "object", "properties": {}}
 }
 ]
}

`tools/call` 返回的结果格式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 成功
{
 "jsonrpc": "2.0", "id": "mid",
 "result": {
 "content": [{"type": "text", "text": "结果文本（JSON 或纯文本）"}]
 }
}

// 失败
{
 "jsonrpc": "2.0", "id": "mid",
 "error": {"code": -32000, "message": "错误描述"}
}

使用 Skill 快速搭建

DeepSeek TUI 内置了 mcp-builder 技能，可以辅助设计、构建和调试 MCP Server：

1

/skill mcp-builder

该 Skill 支持 stdio 和 HTTP/SSE 两种传输方式。

关键点总结

传输：stdio，一行一个 JSON-RPC 消息
协议：必须实现 initialize、tools/list、tools/call
注册：在 ~/.deepseek/mcp.json 的 servers 中添加配置
日志：打到 stderr，不要污染 stdout
结果：content 数组，每项 {"type": "text", "text": "..."}
工具名：TUI 自动加前缀 mcp_<server名>_<工具名>

Ai on XYNRIN-BLOG