Skip to main content
Glama
KURA Notes MCP Client

KURA Notes MCP Client

by TillMatthis

KURA MCP Client

A Model Context Protocol (MCP) client that enables Claude Desktop to interact with KURA Notes API. This standalone client provides semantic search, note creation, retrieval, and management capabilities through Claude's native interface.

Features

  • Semantic Search: Find relevant notes using natural language queries

  • Note Creation: Create text notes with metadata (title, tags, annotations)

  • Note Retrieval: Get specific notes by ID or list recent notes

  • Note Management: Delete notes when needed

  • Robust Error Handling: Clear error messages for API issues

  • Logging: Detailed logging to stderr for debugging

Related MCP server: PersonalKB

Prerequisites

  • Node.js >= 20.0.0

  • Claude Desktop application

  • KURA Notes API access (API key required)

Installation

  1. Clone or download this repository:

    git clone <repository-url>
    cd kura-mcp-client
  2. Install dependencies:

    npm install
  3. Build the project:

    npm run build

    This will:

    • Compile TypeScript to JavaScript

    • Generate the dist/index.js file

    • Make the output file executable

Configuration

For Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kura-notes": {
      "command": "node",
      "args": ["/absolute/path/to/kura-mcp-client/dist/index.js"],
      "env": {
        "API_KEY": "your-kura-api-key-here",
        "KURA_API_URL": "https://kura.tillmaessen.de"
      }
    }
  }
}

Important: Replace /absolute/path/to/kura-mcp-client with the actual absolute path to this project directory.

Environment Variables

  • API_KEY (required): Your KURA Notes API authentication key

  • KURA_API_URL (optional): The KURA API base URL (defaults to https://kura.tillmaessen.de)

Available Tools

1. kura_search

Perform semantic search across your KURA Notes.

Parameters:

  • query (string, required): The search query

  • limit (number, optional): Maximum number of results (default: 10)

  • contentType (string, optional): Filter by content type (e.g., "text")

  • tags (string, optional): Comma-separated tags to filter by

Example:

Search my notes for "machine learning algorithms"

Response: Array of search results with relevance scores and metadata.

2. kura_create

Create a new text note in KURA Notes.

Parameters:

  • content (string, required): The main content of the note

  • title (string, optional): Title for the note

  • annotation (string, optional): Additional context or annotation

  • tags (array of strings, optional): Tags to categorize the note

Example:

Create a note with the content "Today I learned about semantic search"
and tag it with "learning" and "ai"

Response: Created note with ID and metadata.

3. kura_get

Retrieve a specific note by its ID.

Parameters:

  • id (string, required): The unique identifier of the note

Example:

Get the note with ID "abc123"

Response: Full note content and metadata, or error if not found.

4. kura_list_recent

List the 20 most recent notes with metadata (without full content).

Parameters: None

Example:

Show me my recent notes

Response: Array of recent notes with metadata.

5. kura_delete

Delete a note by its ID. This action is permanent.

Parameters:

  • id (string, required): The unique identifier of the note to delete

Example:

Delete the note with ID "abc123"

Response: Success confirmation or error if not found.

Usage Examples

Once configured in Claude Desktop, you can use natural language to interact with your KURA Notes:

  1. Search for notes:

    • "Search my KURA notes for information about TypeScript"

    • "Find notes tagged with 'project-ideas'"

  2. Create notes:

    • "Create a note: 'Meeting notes from today's standup...'"

    • "Save this idea to KURA: 'Build a note-taking MCP client'"

  3. Retrieve notes:

    • "Get the full content of note ID xyz789"

    • "Show me my recent notes"

  4. Delete notes:

    • "Delete note abc123"

Troubleshooting

Server not starting

Symptom: Claude Desktop shows connection error

Solutions:

  • Verify Node.js version: node --version (should be >= 20.0.0)

  • Check the absolute path in claude_desktop_config.json is correct

  • Ensure the project is built: npm run build

  • Check that dist/index.js exists and is executable

API_KEY error

Symptom: "ERROR: API_KEY environment variable is required"

Solutions:

  • Verify API_KEY is set in the env section of your Claude Desktop config

  • Restart Claude Desktop after changing the config

  • Check for typos in the config file

Authentication errors

Symptom: "401 Unauthorized" or "403 Forbidden" errors

Solutions:

  • Verify your API key is correct and active

  • Check if the API key has the necessary permissions

  • Ensure the Authorization header format is correct

Network errors

Symptom: "Failed to fetch" or connection timeout errors

Solutions:

  • Verify KURA_API_URL is correct and accessible

  • Check your internet connection

  • Verify the KURA API service is running

Viewing logs

The MCP client logs to stderr. To view logs:

macOS/Linux:

  1. Close Claude Desktop

  2. Run from terminal:

    /Applications/Claude.app/Contents/MacOS/Claude 2>&1 | grep "KURA MCP"

Windows: Check the Claude Desktop logs in the application data directory.

Development

Project Structure

kura-mcp-client/
├── README.md           # This file
├── LICENSE             # Elastic License 2.0
├── package.json        # Project configuration and dependencies
├── tsconfig.json       # TypeScript compiler configuration
├── .gitignore          # Git ignore rules
├── src/
│   └── index.ts        # Main MCP server implementation
└── dist/
    └── index.js        # Compiled JavaScript (after build)

Development Commands

# Install dependencies
npm install

# Build the project (compile TypeScript)
npm run build

# Run in development mode (with hot reload)
npm run dev

# Clean build artifacts
npm run clean

# Rebuild from scratch
npm run clean && npm run build

Running Tests Manually

You can test the MCP server manually:

# Set environment variables
export API_KEY="your-api-key"
export KURA_API_URL="https://kura.tillmaessen.de"

# Run the server (it will wait for MCP protocol messages on stdin)
node dist/index.js

The server communicates via JSON-RPC over stdin/stdout, so manual testing requires sending properly formatted MCP protocol messages.

Code Structure

The main implementation in src/index.ts includes:

  • TypeScript Interfaces: Type definitions for KURA API responses

  • Environment Validation: Checks for required API_KEY

  • callKuraAPI(): Helper function for authenticated API requests

  • MCP Server Setup: Initializes the MCP server with stdio transport

  • Tool Definitions: Defines the 5 available tools with schemas

  • Request Handlers:

    • ListToolsRequestSchema: Returns available tools

    • CallToolRequestSchema: Executes tool calls with error handling

Adding New Tools

To add new tools:

  1. Add the tool definition to the tools array

  2. Add a new case in the CallToolRequestSchema handler

  3. Implement the API call and response handling

  4. Update this README with the new tool documentation

API Reference

The client interacts with these KURA Notes API endpoints:

  • GET /api/search - Semantic search

  • POST /api/capture - Create notes

  • GET /api/content/{id} - Get specific note

  • GET /api/content/recent - List recent notes

  • DELETE /api/content/{id} - Delete note

All requests include Authorization: Bearer {API_KEY} header.

Technical Details

  • Protocol: Model Context Protocol (MCP) via stdio

  • Transport: JSON-RPC over stdin/stdout

  • Language: TypeScript compiled to ES2022

  • Runtime: Node.js >= 20.0.0

  • SDK: @modelcontextprotocol/sdk v1.x

License

This project is licensed under the Elastic License 2.0 (ELv2).

You are free to use, modify, and self-host this software at no cost. However, you may not provide it to third parties as a hosted or managed service where users access its features or functionality commercially. See the LICENSE file for the full terms.

Contributing

Contributions are welcome! Please ensure:

  • TypeScript code follows the existing style

  • All tools have proper error handling

  • Documentation is updated for new features

  • Code compiles without errors

Support

For issues related to:

  • This MCP client: Check the troubleshooting section above

  • KURA Notes API: Contact your KURA API administrator

  • Claude Desktop: Visit Anthropic's support

  • MCP Protocol: See MCP documentation

Available Tools

5 tools
kura_createB

Create a new text note in KURA Notes. Use this to capture ideas, information, or any text content.

Inputs: content (required), title, annotation, tags.

kura_deleteA

Delete a note by its ID. This action is permanent and cannot be undone.

Inputs: id (required).

kura_getA

Retrieve a specific note by its ID. Returns the full content and metadata.

Inputs: id (required).

kura_list_recentB

List the 20 most recent notes with their metadata (without full content). Use this to get an overview of recent activity.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity: create, delete, get, list recent, and search are all unique operations on notes. The descriptions reinforce this by specifying different actions (e.g., 'create a new text note' vs. 'retrieve a specific note'), making it easy for an agent to select the correct tool.

    Naming Consistency5/5

    All tool names follow a consistent 'kura_verb' pattern (e.g., kura_create, kura_delete), with verbs that clearly indicate the action. There are no deviations in style or convention, making the naming predictable and easy to understand across the set.

    Tool Count5/5

    With 5 tools, this server is well-scoped for a notes management system. Each tool serves a distinct and necessary function (create, delete, get, list, search), covering core operations without being overly complex or too sparse, which is ideal for this domain.

    Completeness4/5

    The tool set provides strong coverage for basic CRUD and search operations on notes, including create, delete, get, list, and semantic search. A minor gap exists in the lack of an update or edit tool, which could be a common need in note-taking workflows, but agents can work around this by deleting and recreating notes if necessary.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables full-text search over personal notes, note and tag management, and live weather lookups through MCP tools, resources, and prompts, usable from clients like Claude Desktop or a custom agent loop.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables a shared persistent knowledge vault for Claude Desktop, allowing notes to be saved, retrieved, searched, updated, and deleted across Chat and Code tabs.
      5
      63 npm
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude Desktop to add, retrieve, update, delete, and list personal notes persisted in a local JSON file, with atomic saves and configurable note storage paths.
      -

    Appeared in Searches