@mauro.pelizzari-doki/doki-mcp-client

v1.0.2

Published

a day ago

MCP Server for Doki - Document Intelligence Platform. Integrates Claude Desktop/Code with Doki for document management.

0High
0Medium
0Low

mauro.pelizzari-doki

mcp model-context-protocol claude anthropic doki ai document-management llm

Doki MCP Server

MCP (Model Context Protocol) server for integrating Claude Desktop/Code with Doki.

Version 2.0 - Now uses JSON-RPC transport for full MCP protocol compliance.

Features

67+ tools dynamically loaded from the Doki server
JSON-RPC transport via /mcp endpoint
OAuth 2.0 authentication with PKCE (recommended)
PAT authentication for API access
Auto token refresh for seamless experience

Installation

From npm (Recommended)

npm install -g @mauro.pelizzari-doki/doki-mcp-client

From source

git clone https://github.com/doki-app/doki.git
cd doki/mcp-client
npm install

Setup

Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Option A: OAuth Authentication (Recommended)

Using npx (no global install needed):

{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "doki": {
      "command": "doki-mcp",
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}

Using local source:

{
  "mcpServers": {
    "doki": {
      "command": "node",
      "args": ["/FULL/PATH/TO/doki/mcp-client/src/index.js"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}

When you first use a Doki tool, a browser window will open for Keycloak login. After authentication, the tokens are saved locally and refreshed automatically.

Option B: PAT Authentication

Create a PAT in Doki (Settings > API Tokens)
Configure Claude Desktop:

{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org",
        "DOKI_API_TOKEN": "doki_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Configure Claude Code

Add to your Claude Code MCP settings (~/.claude/claude_code_mcp_settings.json):

{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}

Or with PAT authentication:

{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org",
        "DOKI_API_TOKEN": "doki_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart Claude

Close and reopen Claude Desktop/Code after configuration changes.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Claude Desktop / Claude Code                               │
└────────────────────────┬────────────────────────────────────┘
                         │ stdio (MCP SDK)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  doki-mcp-client (this package)                             │
│  - Proxies tool calls to Doki                               │
│  - Handles OAuth/PAT authentication                         │
│  - Dynamically fetches available tools                      │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC over HTTP
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Doki Server (/mcp endpoint)                                │
│  - McpServer (JSON-RPC handler)                             │
│  - McpTools (67+ tool implementations)                      │
└─────────────────────────────────────────────────────────────┘

How OAuth Works

When you first call a Doki tool (e.g., "list my Doki projects")
The MCP server starts a local callback server on port 9876
A browser opens with the Keycloak login page
After you authenticate, Keycloak redirects to localhost:9876/callback
The MCP server exchanges the code for tokens
Tokens are saved to ~/.doki-mcp/tokens.json
Subsequent calls use the saved token (auto-refreshed when expired)

To re-authenticate, delete ~/.doki-mcp/tokens.json and restart Claude.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DOKI_URL | Doki server URL | https://doki-app.duckdns.org | | DOKI_API_TOKEN | PAT token (enables PAT mode) | - | | AUTH_MODE | Force auth mode: oauth or pat | Auto-detect | | OAUTH_CLIENT_ID | Keycloak client ID | doki-mcp | | OAUTH_CALLBACK_PORT | Local callback port | 9876 |

Available Tools

Tools are dynamically loaded from the server. Currently available:

Projects

list_projects - List all projects in the organization
get_project - Get project details
create_project - Create a new project
update_project - Update project details
delete_project - Delete a project

Artifacts

list_artifacts - List artifacts in a project
get_artifact - Get artifact with full content
create_artifact - Create new artifact from template
update_artifact_content - Update a section's content
update_artifact_name - Update artifact name
update_artifact_status - Change artifact status
delete_artifact - Delete an artifact
export_artifact_docx - Get DOCX download URL
list_available_sections - List optional sections
add_artifact_section - Add a section to artifact
remove_artifact_section - Remove a section

Paragraphs

list_paragraphs - List paragraphs in an artifact
create_paragraph - Create a new paragraph
update_paragraph - Update paragraph content
reorder_paragraphs - Reorder paragraphs
delete_paragraph - Delete a paragraph

Questions

list_artifact_questions - List questions for an artifact
get_artifact_question - Get question details
create_artifact_question - Create a question
update_artifact_question - Update/answer a question
delete_artifact_question - Delete a question

Tasks

list_artifact_tasks - List tasks for an artifact
get_artifact_task - Get task details
create_artifact_task - Create a task
update_artifact_task - Update a task
delete_artifact_task - Delete a task

Knowledge Sources

list_knowledge_sources - List uploaded documents
get_knowledge_source - Get document content
get_ingestion_status - Check processing status
update_knowledge_source - Update metadata
delete_knowledge_source - Delete a source
retry_knowledge_processing - Retry failed processing
download_knowledge_source - Get download URL

Templates

list_templates - List available templates
get_template - Get template with sections
create_template - Create a new template
update_template - Update template
delete_template - Delete a template
list_template_sections - (via get_template)
create_template_section - Add a section
update_template_section - Update a section
delete_template_section - Delete a section
list_template_versions - List version history
restore_template_version - Restore a version

Clients

list_clients - List all clients
create_client - Create a new client

Project Members

list_project_members - List project members
add_project_member - Add a member
update_project_member - Update member role
remove_project_member - Remove a member

Dashboard

get_my_tasks - Get tasks assigned to you
get_recent_activities - Get recent activities

Activities

list_artifact_activities - Get activity log

Organization

get_organization - Get organization info
get_organization_members - List members

Settings

get_llm_settings - Get LLM configuration
update_llm_settings - Update LLM settings
get_pdf_styles - Get PDF export styles
update_pdf_styles - Update PDF styles

Utilities

list_doki_roles - List available doki roles
list_template_icons - List available icons
list_template_groups - List template groups
create_template_group - Create a group

Troubleshooting

OAuth flow doesn't start

Check that port 9876 is not in use
Try setting a different port: OAUTH_CALLBACK_PORT=9999

"Authentication failed"

Delete ~/.doki-mcp/tokens.json and retry
Check that DOKI_URL is correct and reachable

Browser doesn't open

Manually open the URL shown in stderr
On Linux, ensure xdg-open is installed

Tools not loading

Check server logs for connection errors
Verify the Doki server is running and accessible

Testing

# Test with OAuth (will open browser)
DOKI_URL=https://doki-app.duckdns.org node src/index.js

# Test with PAT
DOKI_API_TOKEN=doki_pat_xxx node src/index.js