内容
# mcp-logseq
Python 标准输入输出 MCP 服务器，用于 Logseq 本地 HTTP API。
## 要求
- Python 3.11+
- 已启用 HTTP API 的 Logseq 桌面版
- Logseq API令牌
在 Logseq 中，从设置中启用 HTTP API 并复制令牌。服务器默认情况下通过 `http://127.0.0.1:12315/api` 调用 Logseq。
## 安装
```bash
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
```
## 在 Codex 中配置
从该项目目录，安装包并将标准输入输出 MCP 服务器添加到 Codex：
```bash
python -m venv .venv
.venv/bin/pip install -e .
codex mcp add logseq \
--env LOGSEQ_API_TOKEN=您的令牌 \
--env LOGSEQ_API_URL=http://127.0.0.1:12315/api \
-- "$(pwd)/.venv/bin/mcp-logseq"
```
在 Windows PowerShell 上，在 `.venv\Scripts` 下使用虚拟环境可执行文件：
```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
codex mcp add logseq `
--env LOGSEQ_API_TOKEN=您的令牌 `
--env LOGSEQ_API_URL=http://127.0.0.1:12315/api `
-- "$((Get-Location).Path)\.venv\Scripts\mcp-logseq.exe"
```
用从 Logseq 获取的令牌替换 `您的令牌`。添加后，重启 Codex 以加载新的 MCP 服务器。
如果您更喜欢手动编辑配置，请从此检出生成 JSON 表单：
```bash
.venv/bin/mcp-logseq --print-config
```
在 Windows 上：
```powershell
.\.venv\Scripts\mcp-logseq.exe --print-config
```
服务器仅为 MCP 客户端提供标准输入输出服务。该 `LOGSEQ_API_URL` 值是此标准输入输出服务器在后台调用的本地 Logseq HTTP API。
### Logseq 设置
1. 打开 Logseq 桌面版。
2. 在 Logseq 设置中启用 HTTP API。
3. 复制 API 令牌。
4. 在 `codex mcp add` 命令中使用该令牌作为 `LOGSEQ_API_TOKEN`。
5. 在使用 MCP 服务器时保持 Logseq 运行。
## 运行
```bash
LOGSEQ_API_TOKEN=您的令牌 mcp-logseq
```
在 Windows PowerShell 上：
```powershell
$env:LOGSEQ_API_TOKEN = "您的令牌"
.\.venv\Scripts\mcp-logseq.exe
```
服务器默认使用标准输入输出传输。不要为期望标准输入输出的 MCP 客户端在 HTTP 服务器后面运行它。
可选环境变量：
- `LOGSEQ_API_URL`：完整的 API URL，默认为 `http://127.0.0.1:12315/api`
- `LOGSEQ_TIMEOUT`：请求超时（秒），默认为 `15`
## 测试
运行完整的本地测试套件：
```bash
.venv/bin/python -m pytest
```
在 Windows 上：
```powershell
.\.venv\Scripts\python.exe -m pytest
```
测试套件涵盖了 Logseq HTTP 客户端、环境加载、MCP 配置生成、标准输入输出启动以及每个导出的服务器工具的 Logseq API 方法/参数映射。
## MCP 客户端配置
从此检出生成一个可以直接复制的配置：
```bash
.venv/bin/mcp-logseq --print-config
```
在 Windows 上：
```powershell
.\.venv\Scripts\mcp-logseq.exe --print-config
```
然后将 JSON 粘贴到您的 MCP 客户端配置中。一个静态示例也可在 `mcp.example.json` 中找到。
```json
{
"mcpServers": {
"logseq": {
"command": "/绝对路径/to/mcp-logseq/.venv/bin/mcp-logseq",
"args": [],
"env": {
"LOGSEQ_API_TOKEN": "您的令牌",
"LOGSEQ_API_URL": "http://127.0.0.1:12315/api"
}
}
}
}
```
Windows 手动配置示例：
```json
{
"mcpServers": {
"logseq": {
"command": "C:\\Users\\您\\路径\\到\\mcp-logseq\\.venv\\Scripts\\mcp-logseq.exe",
"args": [],
"env": {
"LOGSEQ_API_TOKEN": "您的令牌",
"LOGSEQ_API_URL": "http://127.0.0.1:12315/api"
}
}
}
}
```
## 工具
通用：
- `logseq_call`：按名称调用任何 Logseq API 方法。
应用和图谱：
- `get_current_graph`
- `get_current_graph_configs`
- `get_current_graph_favorites`
- `get_current_graph_recent`
- `get_current_graph_templates`
- `get_user_configs`
- `get_app_info`
- `check_current_is_db_graph`
页面和块：
- `get_current_page`
- `get_current_block`
- `get_current_page_blocks_tree`
- `get_all_pages`
- `get_page`
- `get_page_blocks_tree`
- `get_page_linked_references`
- `get_page_properties`
- `get_pages_from_namespace`
- `get_pages_tree_from_namespace`
- `get_block`
- `get_block_properties`
- `get_block_property`
- `get_previous_sibling_block`
- `get_next_sibling_block`
- `search`
查询：
- `query`
- `datascript_query`
页面编辑：
- `create_page`
- `create_journal_page`
- `rename_page`
- `delete_page`
块编辑：
- `append_block_in_page`
- `prepend_block_in_page`
- `insert_block`
- `insert_batch_block`
- `move_block`
- `update_block`
- `remove_block`
- `new_block_uuid`
- `set_block_collapsed`
- `set_block_icon`
- `remove_block_icon`
属性和标签：
- `get_all_tags`
- `get_all_properties`
- `upsert_block_property`
- `remove_block_property`
- `upsert_property`
- `remove_property`
- `create_tag`
- `get_tag`
- `get_tags_by_name`
- `get_tag_objects`
- `add_block_tag`
- `remove_block_tag`
- `add_tag_extends`
- `remove_tag_extends`
- `add_tag_property`
- `remove_tag_property`
资产和 Git：
- `list_asset_files`
- `make_asset_url`
- `open_asset`
- `git_exec`
- `git_load_ignore_file`
- `git_save_ignore_file`
用于修改图谱的工具故意直接封装了 Logseq 的 API。使用它们时请使用明确的页面名称、UUID 和内容。插件回调/钩子 API 未作为一流工具公开，因为标准输入输出 MCP 服务器无法托管交互式 Logseq 插件回调；仅使用 `logseq_call` 进行一次性方法调用。
