@journai/base-mcp-server

MCP Server for Journai Base — enables AI agents (Claude Code, Claude Desktop, Cursor) to interact with your knowledge platform.

Quick Start

Add this to your .mcp.json (Claude Code) or MCP client config:

{
  "mcpServers": {
    "journai": {
      "command": "npx",
      "args": ["-y", "@journai/base-mcp-server"],
      "env": {
        "JOURNAI_URL": "https://base.journai.ch",
        "JOURNAI_API_KEY": "jnai_your_api_key_here"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "journai": {
      "command": "npx",
      "args": ["-y", "@journai/base-mcp-server"],
      "env": {
        "JOURNAI_URL": "http://localhost:3000",
        "JOURNAI_API_KEY": "jnai_your_dev_api_key"
      }
    }
  }
}

Prerequisites

1. A Journai Base account with API key access
2. Create an API key: Go to Settings > API Keys and create a key with the scopes you need
3. Node.js >= 18

Available Tools

Pages

| Tool | Description | Required Scope | |------|-------------|----------------| | journai_search_pages | Full-text search across all pages | search:read | | journai_get_page | Get a page by ID with full markdown content | pages:read | | journai_create_page | Create a new page in a space | pages:write | | journai_update_page | Update page title or content (append/prepend/replace) | pages:write | | journai_list_pages | List top-level pages in a space | pages:read | | journai_list_child_pages | List child pages of a parent page | pages:read | | journai_duplicate_page | Duplicate a page within the same space | pages:write | | journai_move_page | Move a page (reorder or cross-space) | pages:write | | journai_copy_page_to_space | Copy a page to a different space | pages:write |

Spaces

| Tool | Description | Required Scope | |------|-------------|----------------| | journai_get_space | Get space details by ID | spaces:read | | journai_list_spaces | List all spaces you have access to | spaces:read | | journai_create_space | Create a new space | spaces:write | | journai_update_space | Update space name or description | spaces:write |

Comments

| Tool | Description | Required Scope | |------|-------------|----------------| | journai_get_comments | Get comments on a page | comments:read | | journai_create_comment | Add a comment to a page (plain text) | comments:write | | journai_update_comment | Update a comment (plain text) | comments:write |

Search & Other

| Tool | Description | Required Scope | |------|-------------|----------------| | journai_search_suggestions | Autocomplete search for pages/users | search:read | | journai_search_attachments | Search for file attachments | pages:read | | journai_list_workspace_members | List workspace members | workspace:read | | journai_get_current_user | Get current user and workspace info | users:read |

Resources

| URI Pattern | Description | |-------------|-------------| | page://{pageId} | Read page content as markdown | | space://{spaceId}/pages | List pages in a space |

Configuration

| Environment Variable | Required | Description | |---------------------|----------|-------------| | JOURNAI_URL | Yes | Journai Base instance URL (e.g. https://base.journai.ch or http://localhost:3000) | | JOURNAI_API_KEY | Yes | API key starting with jnai_ — create in Settings > API Keys |

API Key Scopes

Your API key determines what the MCP server can do. Available scopes:

• pages:read / pages:write — Read and modify pages
• spaces:read / spaces:write — Read and modify spaces
• comments:read / comments:write — Read and modify comments
• search:read — Search pages and attachments
• users:read — View user information
• workspace:read — View workspace members

A key with only pages:read will get a clear error message when trying to use write tools.

Development

git clone https://github.com/journai-ch/journai-base-mcp-server.git
cd journai-base-mcp-server
pnpm install
pnpm dev          # Run with tsx (needs JOURNAI_URL and JOURNAI_API_KEY env vars)
pnpm test         # Run tests
pnpm build        # Build for production
pnpm typecheck    # TypeScript type checking

License

MIT