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
Prerequisites
- Node.js >= 20.0.0
- Claude Desktop application
- KURA Notes API access (API key required)
Installation
-
Clone or download this repository:
git clone <repository-url> cd kura-mcp-client -
Install dependencies:
npm install -
Build the project:
npm run buildThis will:
- Compile TypeScript to JavaScript
- Generate the
dist/index.jsfile - 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 keyKURA_API_URL(optional): The KURA API base URL (defaults tohttps://kura.tillmaessen.de)
Available Tools
1. kura_search
Perform semantic search across your KURA Notes.
Parameters:
query(string, required): The search querylimit(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 notetitle(string, optional): Title for the noteannotation(string, optional): Additional context or annotationtags(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:
-
Search for notes:
- "Search my KURA notes for information about TypeScript"
- "Find notes tagged with 'project-ideas'"
-
Create notes:
- "Create a note: 'Meeting notes from today's standup...'"
- "Save this idea to KURA: 'Build a note-taking MCP client'"
-
Retrieve notes:
- "Get the full content of note ID xyz789"
- "Show me my recent notes"
-
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.jsonis correct - Ensure the project is built:
npm run build - Check that
dist/index.jsexists and is executable
API_KEY error
Symptom: "ERROR: API_KEY environment variable is required"
Solutions:
- Verify
API_KEYis set in theenvsection 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
Authorizationheader format is correct
Network errors
Symptom: "Failed to fetch" or connection timeout errors
Solutions:
- Verify
KURA_API_URLis 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:
- Close Claude Desktop
- 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
├── 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 toolsCallToolRequestSchema: Executes tool calls with error handling
Adding New Tools
To add new tools:
- Add the tool definition to the
toolsarray - Add a new case in the
CallToolRequestSchemahandler - Implement the API call and response handling
- Update this README with the new tool documentation
API Reference
The client interacts with these KURA Notes API endpoints:
GET /api/search- Semantic searchPOST /api/capture- Create notesGET /api/content/{id}- Get specific noteGET /api/content/recent- List recent notesDELETE /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
MIT
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