# mcp-jumpserver

面向 Codex 的 JumpServer STDIO MCP。使用 JumpServer URL、用户名和密码自动登录并缓存 API
Token，无需手工创建 Token。

## 工具

- `test_jumpserver_login`：测试用户名密码登录，不返回 Token。
- `list_jumpserver_databases`：查询数据库资产。
- `list_jumpserver_database_accounts`：查询资产下的账号，不返回密码。
- `get_jumpserver_temporary_database_credential`：签发数据库代理临时用户名和密码，
  与 JumpServer Web 终端的“数据库连接信息”一致。
- `get_jumpserver_configured_database_credentials`：无参数，一次签发配置数组内所有数据库资产的
  临时用户名和密码。

## 安装

```bash
uv sync
```

建议使用权限最小化的独立 JumpServer 用户，不要使用超级管理员。签发临时连接凭证需要
该用户拥有目标资产、账号和协议的登录授权；登录 ACL 的审批或 MFA 策略仍然有效。
本 MCP 不提供底层账号静态密码读取工具，也不需要 `accounts.view_accountsecret` 权限。

## 配置 Codex

```bash
codex mcp add jumpserver -- \
  /absolute/path/to/mcp-jumpserver/.venv/bin/mcp-jumpserver
```

也可以写入 `~/.codex/config.toml`：

```toml
[mcp_servers.jumpserver]
command = "/absolute/path/to/mcp-jumpserver/.venv/bin/mcp-jumpserver"
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

[mcp_servers.jumpserver.env]
JUMPSERVER_URL = "https://jumpserver.example.com"
JUMPSERVER_USERNAME = "codex-service-user"
JUMPSERVER_PASSWORD = "change-me"
JUMPSERVER_VERIFY_SSL = "true"
JUMPSERVER_DATABASE_ASSETS = '["DB-正式mysql-A", "DB-正式mysql-B"]'
# 可选：JUMPSERVER_ORG_ID = "组织 UUID"
```

配置后在 Codex/ChatGPT 桌面端重启该 MCP，再调用 `test_jumpserver_login`。

## 获取数据库临时凭证

日常直接无参数调用：

```text
调用 get_jumpserver_configured_database_credentials
```

结果中的 `credentials` 按配置顺序返回，消费前必须确认 `errors` 为空。需要临时查询配置外资产时，
再按资产精确名称调用单资产工具：

```text
调用 get_jumpserver_temporary_database_credential：
{"asset":"DB-正式mysql-A","protocol":"mysql"}

调用 get_jumpserver_temporary_database_credential：
{"asset":"DB-正式mysql-B","protocol":"mysql"}
```

返回的 `connection.username` 和 `connection.password` 是 JumpServer 数据库代理的临时凭证；
`connection.host`、`connection.port`、`connection.database` 是完整连接地址。如果资产授权了多个
账号，先指定 `account` 的用户名或 UUID。

## 安全说明

- Token 仅缓存在 MCP 进程内存中，收到 HTTP 401 后自动重新登录一次。
- 日志和异常不会输出 JumpServer 密码或 Token。
- MCP 只签发 JumpServer 数据库代理临时凭据，不读取底层数据库账号的静态密码。
- `get_jumpserver_temporary_database_credential` 返回短期明文连接凭证，也仅应在用户明确授权时调用。

## 测试

```bash
uv run pytest
uv run ruff check .
```