# MCP server for LogSeq
MCP server to interact with LogSeq via its API. Enables Claude to read, create, and manage LogSeq pages through a comprehensive set of tools.
## Prerequisites
### LogSeq Setup
1. **Install LogSeq** if not already installed
2. **Enable HTTP APIs server** in LogSeq:
- Go to Settings → Features
- Check "Enable HTTP APIs server"
3. **Start the API server**:
- Look for the API button (🔌) in the main LogSeq interface
- Click it to open the API control panel
- Click "Start server" to start the HTTP API server at `http://localhost:12315`
4. **Generate API token**:
- In the API control panel, click "Authorization tokens"
- Create a new token (e.g., name it "logseq" or "claude")
- Copy the generated token for use in configuration
### System Requirements
- [uv](https://docs.astral.sh/uv/) Python package manager
- LogSeq running with HTTP API enabled
- An MCP client (instructions provided for Claude Code and Claude Desktop)
## Installation
**No package installation required!** This MCP server uses uv's `--with` feature to automatically fetch and run the package. Just add the configuration below to your MCP client:
### Claude Code
```bash
claude mcp add mcp-logseq \
--env LOGSEQ_API_TOKEN=your_token_here \
--env LOGSEQ_API_URL=http://localhost:12315 \
-- uv run --with mcp-logseq mcp-logseq
```
### Claude Desktop
1. **Open Claude Desktop configuration**:
- **macOS**: Claude Desktop → Settings → Developer → "Edit Config"
- **Windows**: Navigate to `%APPDATA%\Claude\claude_desktop_config.json`
2. **Add server configuration**:
```json
{
"mcpServers": {
"mcp-logseq": {
"command": "uv",
"args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
"env": {
"LOGSEQ_API_TOKEN": "your_token_here",
"LOGSEQ_API_URL": "http://localhost:12315"
}
}
}
}
```
3. **Restart Claude Desktop** for changes to take effect
### Other MCP Clients
For other MCP clients, you can use either approach:
**Option 1 - Direct command** (if globally installed):
```
mcp-logseq
```
**Option 2 - Via uv** (recommended):
```
uv run --with mcp-logseq mcp-logseq
```
**Environment variables needed**:
- `LOGSEQ_API_TOKEN`: Your LogSeq API token
- `LOGSEQ_API_URL`: LogSeq server URL (default: `http://localhost:12315`)
### Installation Verification
#### Test LogSeq API connectivity
```bash
uv run --with mcp-logseq python -c "
from mcp_logseq.logseq import LogSeq
api = LogSeq(api_key='your_token')
result = api.list_pages()
print(f'Connected! Found {len(result)} pages')
"
```
#### Verify MCP server registration
```bash
# For Claude Code
claude mcp list
# Should show mcp-logseq in the list
```
#### Test with MCP Inspector (for debugging)
```bash
npx @modelcontextprotocol/inspector uv run --with mcp-logseq mcp-logseq
```
## Tools
The server implements 6 tools to interact with LogSeq:
- **create_page**: Create a new page with content
- **list_pages**: List all pages in the current graph (with journal filtering)
- **get_page_content**: Retrieve content of a specific page (text or JSON format)
- **delete_page**: Remove a page from the graph
- **update_page**: Update existing page content and/or properties
- **search**: Search for content across pages, blocks, and files
### Example prompts
It's good to first instruct Claude to use LogSeq. Then it will always call the tool.
Example prompts:
- Get the contents of my latest meeting notes and summarize them
- Search for all pages where Project X is mentioned and explain the context
- Create a new page with today's meeting notes
- Update the project status page with the latest updates
## Configuration
### Environment Variables
- **LOGSEQ_API_TOKEN** (required): Bearer token from LogSeq API control panel → Authorization tokens
- **LOGSEQ_API_URL** (optional): LogSeq server URL (default: `http://localhost:12315`)
### Alternative Configuration Methods
#### Using .env file
Create a `.env` file in the project directory:
```
LOGSEQ_API_TOKEN=your_token_here
LOGSEQ_API_URL=http://localhost:12315
```
#### Using system environment variables
```bash
export LOGSEQ_API_TOKEN=your_token_here
export LOGSEQ_API_URL=http://localhost:12315
```
## Troubleshooting
### Common Issues
#### "LOGSEQ_API_TOKEN environment variable required"
- Ensure LogSeq HTTP API is enabled in Settings → Features
- Start the API server using the API button (🔌) in LogSeq's main interface
- Generate and copy the API token from "Authorization tokens" in the API control panel
- Verify token is correctly set in your configuration
#### Connection errors to LogSeq
- Confirm LogSeq is running
- Check that HTTP API server is enabled in Settings → Features
- **Important**: Make sure the API server is actually started (click "Start server" in the API control panel)
- Verify the server is running on port 12315
- Test connectivity with the verification command above
#### MCP server not found in Claude Code
- Run `claude mcp list` to check if server is registered
- Verify the command and arguments in your configuration
- Check that `uv` is installed: [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
#### "spawn uv ENOENT" error in Claude Desktop
This error means Claude Desktop cannot find the `uv` command. Claude Desktop may have a limited PATH environment.
**Solution**: Use the full path to uv in your configuration:
1. Find your uv location: `which uv`
2. Update your Claude Desktop config to use the full path:
```json
{
"mcpServers": {
"mcp-logseq": {
"command": "/Users/yourusername/.local/bin/uv",
"args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
"env": {
"LOGSEQ_API_TOKEN": "your_token_here",
"LOGSEQ_API_URL": "http://localhost:12315"
}
}
}
}
```
Common uv locations:
- **uv installed via curl**: `~/.local/bin/uv`
- **uv installed via homebrew**: `/opt/homebrew/bin/uv`
- **uv installed via pip**: Check with `which uv`
#### Empty or missing page content
- Some LogSeq versions may not support all API methods
- Check LogSeq logs for API errors
- Verify page names match exactly (case-sensitive)
## Development
For local development, testing, and contributing to this project, see [DEVELOPMENT.md](DEVELOPMENT.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-logseq",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "knowledge-management, logseq, mcp, model-context-protocol",
"author": null,
"author_email": "Salih Erg\u00fct <salih.ergut@oredata.com>",
"download_url": "https://files.pythonhosted.org/packages/a8/ba/aca16ccf04124b1e00d67a39c59ab90a764f90e34086a69d7db6f7be61e9/mcp_logseq-1.0.1.tar.gz",
"platform": null,
"description": "# MCP server for LogSeq\n\nMCP server to interact with LogSeq via its API. Enables Claude to read, create, and manage LogSeq pages through a comprehensive set of tools.\n\n## Prerequisites\n\n### LogSeq Setup\n1. **Install LogSeq** if not already installed\n2. **Enable HTTP APIs server** in LogSeq:\n - Go to Settings \u2192 Features\n - Check \"Enable HTTP APIs server\"\n3. **Start the API server**:\n - Look for the API button (\ud83d\udd0c) in the main LogSeq interface\n - Click it to open the API control panel\n - Click \"Start server\" to start the HTTP API server at `http://localhost:12315`\n4. **Generate API token**:\n - In the API control panel, click \"Authorization tokens\"\n - Create a new token (e.g., name it \"logseq\" or \"claude\")\n - Copy the generated token for use in configuration\n\n### System Requirements\n- [uv](https://docs.astral.sh/uv/) Python package manager\n- LogSeq running with HTTP API enabled\n- An MCP client (instructions provided for Claude Code and Claude Desktop)\n\n## Installation\n\n**No package installation required!** This MCP server uses uv's `--with` feature to automatically fetch and run the package. Just add the configuration below to your MCP client:\n\n### Claude Code\n\n```bash\nclaude mcp add mcp-logseq \\\n --env LOGSEQ_API_TOKEN=your_token_here \\\n --env LOGSEQ_API_URL=http://localhost:12315 \\\n -- uv run --with mcp-logseq mcp-logseq\n```\n\n### Claude Desktop\n\n1. **Open Claude Desktop configuration**:\n - **macOS**: Claude Desktop \u2192 Settings \u2192 Developer \u2192 \"Edit Config\"\n - **Windows**: Navigate to `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. **Add server configuration**:\n```json\n{\n \"mcpServers\": {\n \"mcp-logseq\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--with\", \"mcp-logseq\", \"mcp-logseq\"],\n \"env\": {\n \"LOGSEQ_API_TOKEN\": \"your_token_here\",\n \"LOGSEQ_API_URL\": \"http://localhost:12315\"\n }\n }\n }\n}\n```\n\n3. **Restart Claude Desktop** for changes to take effect\n\n### Other MCP Clients\n\nFor other MCP clients, you can use either approach:\n\n**Option 1 - Direct command** (if globally installed):\n```\nmcp-logseq\n```\n\n**Option 2 - Via uv** (recommended):\n```\nuv run --with mcp-logseq mcp-logseq\n```\n\n**Environment variables needed**:\n- `LOGSEQ_API_TOKEN`: Your LogSeq API token \n- `LOGSEQ_API_URL`: LogSeq server URL (default: `http://localhost:12315`)\n\n### Installation Verification\n\n#### Test LogSeq API connectivity\n```bash\nuv run --with mcp-logseq python -c \"\nfrom mcp_logseq.logseq import LogSeq\napi = LogSeq(api_key='your_token')\nresult = api.list_pages()\nprint(f'Connected! Found {len(result)} pages')\n\"\n```\n\n#### Verify MCP server registration\n```bash\n# For Claude Code\nclaude mcp list\n\n# Should show mcp-logseq in the list\n```\n\n#### Test with MCP Inspector (for debugging)\n```bash\nnpx @modelcontextprotocol/inspector uv run --with mcp-logseq mcp-logseq\n```\n\n## Tools\n\nThe server implements 6 tools to interact with LogSeq:\n\n- **create_page**: Create a new page with content\n- **list_pages**: List all pages in the current graph (with journal filtering)\n- **get_page_content**: Retrieve content of a specific page (text or JSON format)\n- **delete_page**: Remove a page from the graph\n- **update_page**: Update existing page content and/or properties\n- **search**: Search for content across pages, blocks, and files\n\n### Example prompts\n\nIt's good to first instruct Claude to use LogSeq. Then it will always call the tool.\n\nExample prompts:\n- Get the contents of my latest meeting notes and summarize them\n- Search for all pages where Project X is mentioned and explain the context\n- Create a new page with today's meeting notes\n- Update the project status page with the latest updates\n\n## Configuration\n\n### Environment Variables\n\n- **LOGSEQ_API_TOKEN** (required): Bearer token from LogSeq API control panel \u2192 Authorization tokens\n- **LOGSEQ_API_URL** (optional): LogSeq server URL (default: `http://localhost:12315`)\n\n### Alternative Configuration Methods\n\n#### Using .env file\nCreate a `.env` file in the project directory:\n```\nLOGSEQ_API_TOKEN=your_token_here\nLOGSEQ_API_URL=http://localhost:12315\n```\n\n#### Using system environment variables\n```bash\nexport LOGSEQ_API_TOKEN=your_token_here\nexport LOGSEQ_API_URL=http://localhost:12315\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"LOGSEQ_API_TOKEN environment variable required\"\n- Ensure LogSeq HTTP API is enabled in Settings \u2192 Features\n- Start the API server using the API button (\ud83d\udd0c) in LogSeq's main interface\n- Generate and copy the API token from \"Authorization tokens\" in the API control panel\n- Verify token is correctly set in your configuration\n\n#### Connection errors to LogSeq\n- Confirm LogSeq is running\n- Check that HTTP API server is enabled in Settings \u2192 Features\n- **Important**: Make sure the API server is actually started (click \"Start server\" in the API control panel)\n- Verify the server is running on port 12315\n- Test connectivity with the verification command above\n\n#### MCP server not found in Claude Code\n- Run `claude mcp list` to check if server is registered\n- Verify the command and arguments in your configuration\n- Check that `uv` is installed: [Install uv](https://docs.astral.sh/uv/getting-started/installation/)\n\n#### \"spawn uv ENOENT\" error in Claude Desktop\nThis error means Claude Desktop cannot find the `uv` command. Claude Desktop may have a limited PATH environment.\n\n**Solution**: Use the full path to uv in your configuration:\n\n1. Find your uv location: `which uv` \n2. Update your Claude Desktop config to use the full path:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-logseq\": {\n \"command\": \"/Users/yourusername/.local/bin/uv\",\n \"args\": [\"run\", \"--with\", \"mcp-logseq\", \"mcp-logseq\"],\n \"env\": {\n \"LOGSEQ_API_TOKEN\": \"your_token_here\",\n \"LOGSEQ_API_URL\": \"http://localhost:12315\"\n }\n }\n }\n}\n```\n\nCommon uv locations:\n- **uv installed via curl**: `~/.local/bin/uv`\n- **uv installed via homebrew**: `/opt/homebrew/bin/uv`\n- **uv installed via pip**: Check with `which uv`\n\n#### Empty or missing page content\n- Some LogSeq versions may not support all API methods\n- Check LogSeq logs for API errors\n- Verify page names match exactly (case-sensitive)\n\n## Development\n\nFor local development, testing, and contributing to this project, see [DEVELOPMENT.md](DEVELOPMENT.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "MCP server to work with LogSeq via the local HTTP server",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/ergut/mcp-logseq/issues",
"Homepage": "https://github.com/ergut/mcp-logseq",
"Source": "https://github.com/ergut/mcp-logseq"
},
"split_keywords": [
"knowledge-management",
" logseq",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "74aace21e166101d19f08b7112940a6e292a54d191434246724ab686f0317ef9",
"md5": "9431a5aa6f7d92f9cee4b2d4a9d66cea",
"sha256": "dfb3a5c6316209251abffaaf95ec99d8079ca1ba5cbff2ee6ca964028ac95fba"
},
"downloads": -1,
"filename": "mcp_logseq-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9431a5aa6f7d92f9cee4b2d4a9d66cea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 12318,
"upload_time": "2025-08-21T08:42:54",
"upload_time_iso_8601": "2025-08-21T08:42:54.503351Z",
"url": "https://files.pythonhosted.org/packages/74/aa/ce21e166101d19f08b7112940a6e292a54d191434246724ab686f0317ef9/mcp_logseq-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a8baaca16ccf04124b1e00d67a39c59ab90a764f90e34086a69d7db6f7be61e9",
"md5": "be6a5af009a81cf8c60d0912bb9ff3b9",
"sha256": "e727c6299ea69283ab91fbda198b61137ac4e80217291e55039f4d7ed0f7337a"
},
"downloads": -1,
"filename": "mcp_logseq-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "be6a5af009a81cf8c60d0912bb9ff3b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 32710,
"upload_time": "2025-08-21T08:42:55",
"upload_time_iso_8601": "2025-08-21T08:42:55.458736Z",
"url": "https://files.pythonhosted.org/packages/a8/ba/aca16ccf04124b1e00d67a39c59ab90a764f90e34086a69d7db6f7be61e9/mcp_logseq-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 08:42:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ergut",
"github_project": "mcp-logseq",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mcp-logseq"
}
JSON
