Tasknote Bridge MCP

🚀 TaskNote Bridge - Swift MCP Server with Things 3 & Apple Notes ✅

TaskNote Bridge is a native macOS Swift application that implements a complete Model Context Protocol (MCP) server, enabling seamless integration between Things 3 and Apple Notes.

Status: ✅ PRODUCTION READY - Complete MCP server with GUI monitoring

🚀 Quick Start

📥 Download & Install

1. Download the latest release
2. Open the DMG and drag TaskNote Bridge to Applications.
3. Launch the app - the MCP server starts automatically.
4. Configure VS Code with the settings below.

⚙️ Claude Desktop Configuration

Add this to your Claude Desktop MCP server configuration:

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

⚠️ Important Note

Replace /path/to/tasknote-bridge/ with your actual installation directory. For example:

• If you downloaded the release: /Users/[username]/Downloads/tasknote-bridge/
• If you cloned the repo: /Users/[username]/Projects/tasknote-bridge/
• If you moved it to Applications: /Applications/TaskNote Bridge/

⚙️ VS Code Configuration

Add this to your VS Code settings.json:

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh",
                "args": []
            }
        }
    }
}

🎉 That's it! You're ready to create tasks and notes via AI assistants.

📋 Requirements

• macOS: 12.0+ (Monterey or later)
• Things 3: Install from Mac App Store.
• Apple Notes: Built into macOS.
• VS Code: With MCP extension.

💻 Usage Examples

Basic Usage

# Test the stdio server (creates task in Things 3!)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Hello from VS Code!", "tags": ["test"]}}}' | ./launch_swift_mcp_stdio.sh

# Expected output:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ Task 'Hello from VS Code!' created in Things 3","type":"text"}],"isError":false}}

# ✅ Check Things 3 - your task will be there!

Advanced Usage

# For GUI Monitoring
# Build and run the macOS app
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# Server auto-starts with monitoring interface

✨ Features

Native macOS MCP Server Application

• Complete MCP Server: Full Swift implementation of MCP protocol with Things 3 and Apple Notes tools.
• Real-time Monitoring: Server status dashboard with live activity tracking.
• TCP Transport: Network-based transport protocol for universal MCP client compatibility.
• Log Streaming: Live server logs with filtering and search capabilities.
• Connection Management: Monitor active client connections and request/response activity.
• SwiftUI Interface: Modern macOS interface for server monitoring and control.

Things 3 Integration

• Access to all major Things lists (Inbox, Today, Upcoming, etc.).
• Project and area management.
• Tag operations.
• Advanced search capabilities.
• Recent items tracking.
• Detailed item information including checklists.
• Support for nested data (projects within areas, todos within projects).
• Open specific tasks directly in Things 3 app.

Apple Notes Integration

• Create new notes with titles, content, and tags.
• Search notes by title.
• Retrieve note content.
• List all notes.
• Open notes directly in Apple Notes app.
• Delete notes.
• Full AppleScript integration for seamless macOS experience.

📦 Installation

Option 1: Download the App (Recommended)

Download the latest TaskNote Bridge.app from the Releases page.

Option 2: Build from Source

If you prefer to build from source, you'll need:

• Xcode 14.0 or newer.
• macOS 13.0 or newer.

Clone the repository and build:

# Clone the repository
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp

# Open in Xcode and build
open "TaskNote Bridge.xcodeproj"

Configuration

Prerequisites

• Any MCP-compatible AI assistant or tool (Claude Desktop, VS Code with MCP extensions, Cursor, Continue, Zed, etc.).
• Things 3 ("Enable Things URLs" must be turned on in Settings -> General).
• Apple Notes (for note management features).
• macOS 13.0 or newer (required for SwiftUI and AppleScript integration).

🔧 Technical Details

Project Architecture

This project provides two MCP server implementations for different use cases:

📱 TaskNote Bridge.app (GUI Application)

• Purpose: macOS app with visual monitoring interface.
• Transport: TCP server (port 8000) for network-based connections.
• Features: Real-time dashboard, connection monitoring, log viewer.
• Use Case: When you want visual monitoring of server activity.
• Launch: Open the app from Applications folder.

📟 swift_mcp_stdio.swift (Command-Line Server)

• Purpose: Lightweight stdio-based MCP server.
• Transport: Standard input/output communication.
• Features: Direct JSON-RPC message handling, minimal overhead.
• Use Case: Recommended for Claude Desktop and most MCP clients.
• Launch: Via launch_swift_mcp_stdio.sh script.

🔧 Which One to Use?

💡 Usage Tip

Most MCP clients (including Claude Desktop) expect stdio-based communication, not TCP connections.

🔗 MCP Client Connection Guide

TaskNote Bridge supports multiple connection methods to work with various MCP clients. Choose the method that works best for your client:

🎯 Claude Desktop

Configure Claude Desktop to use the stdio-based MCP server:

1. Open Claude Desktop
2. Click the settings gear (⚙️) in the bottom left.
3. Select "Developer"
4. In the "MCP Servers" section, click "Edit Config"
5. Add this configuration:

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

⚠️ Important Note

Replace /path/to/tasknote-bridge/ with your actual installation directory. Common paths:

• Downloaded release: /Users/[username]/Downloads/tasknote-bridge/launch_swift_mcp_stdio.sh
• Cloned repository: /Users/[username]/Projects/tasknote-bridge/launch_swift_mcp_stdio.sh
• App bundle install: /Applications/TaskNote Bridge.app/Contents/Resources/launch_swift_mcp_stdio.sh

6. Save the configuration
7. Restart Claude Desktop to apply the changes

✅ Success: Claude Desktop will now connect via stdio transport, which is the recommended and most reliable method for MCP communication.

🔧 VS Code with MCP Extension

1. Install the MCP extension for VS Code:
   • Open VS Code Extensions (Cmd+Shift+X).
   • Search for "Model Context Protocol" and install.
2. Configure VS Code settings (settings.json):

{
    "mcp": {
        "servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

3. Restart VS Code to load the MCP server.

🖱️ Cursor IDE

1. Open Cursor Settings (Cmd+,)
2. Navigate to Extensions → Model Context Protocol
3. Add server configuration:

{
    "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
    "args": []
}

⚡ Continue (VS Code Extension)

1. Install Continue extension in VS Code.
2. Open Continue config (usually ~/.continue/config.json).
3. Add MCP server:

{
    "mcpServers": [
        {
            "name": "tasknote-bridge",
            "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
            "args": []
        }
    ]
}

🚀 Zed Editor

1. Open Zed Settings (Cmd+,)
2. Add to your settings.json:

{
    "assistant": {
        "mcp_servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh"
            }
        }
    }
}

🛠️ Custom MCP Clients

For any custom MCP client or application:

TCP Connection

• Host: localhost
• Port: 8000 (default, configurable in TaskNote Bridge app)
• Protocol: TCP with JSON-RPC 2.0

Stdio Connection

• Command: /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
• Transport: Standard input/output with JSON-RPC 2.0

📋 Verification Steps

After configuring any client:

1. Test connection:

   # For stdio testing
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   
   # For TCP testing (if server is running)
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc localhost 8000
   

2. Check for available tools - you should see tools like:

   • bb7_add-todo
   • bb7_add-project
   • bb7_get-today
   • bb7_notes-create
   • And many more...

3. Test task creation:

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Test from MCP!", "tags": ["test"]}}}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   

4. Verify in Things 3 - the test task should appear in your Inbox.

🔍 Troubleshooting Connection Issues

Claude Desktop Not Connecting

• Check that the config file is valid JSON.
• Verify the file path exists: /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh.
• Restart Claude Desktop completely.
• Check Claude logs: ~/Library/Logs/Claude/mcp*.log.

TCP Connection Issues

• Ensure TaskNote Bridge app is running.
• Check if port 8000 is available: lsof -i :8000.
• Try a different port in TaskNote Bridge settings.
• Verify firewall settings allow local connections.

Stdio Connection Issues

• Verify script permissions: ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh.
• Test script directly in terminal.
• Check that Things 3 URLs are enabled in Things 3 → Settings → General.

For VS Code (with MCP extension)

1. First, ensure you have the TaskNote Bridge app installed and running.

2. Install the MCP extension for VS Code:

   • Open VS Code.
   • Go to Extensions (Cmd+Shift+X).
   • Search for "MCP" and install the official MCP extension.

3. Configure VS Code settings:

   • Open Settings (Cmd+,).
   • Click "Open Settings (JSON)" in the top right.
   • Add this configuration:

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

⚠️ Important Note

Replace the path with the actual location where you installed the app. If you moved it to your Applications folder, use: /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh

4. Restart VS Code to load the MCP server.

Usage

In the TaskNote Bridge App

1. Launch the TaskNote Bridge app from your Applications folder.
2. The app provides a native macOS interface for:
   • Viewing your Things 3 tasks, projects, and areas.
   • Managing your Apple Notes.
   • Monitoring MCP server connections.
   • Seeing activity logs in real-time.

In Claude Desktop

Once connected, you can interact with TaskNote Bridge using natural language:

Things 3 Examples:

• "What's on my todo list today?"
• "Create a todo to pack for my beach vacation next week"
• "Create a project for Memorial Day BBQ with planning tasks"
• "Show me all my work-related tasks"
• "Mark the grocery shopping task as completed"
• "Add a task to call mom tomorrow"

Apple Notes Examples:

• "Create a note with meeting minutes from today's standup"
• "Search my notes for anything about the quarterly review"
• "Make a note about the new restaurant I want to try"
• "Show me all my notes with travel information"

In VS Code

With the MCP extension installed and configured:

1. Open the Command Palette (Cmd+Shift+P).
2. Type "MCP" to see available MCP commands.
3. Use "MCP: Call Tool" to interact with Things tools.
4. Or use any AI assistant that supports MCP to access your Things data.

For Any MCP-Compatible Tool

This server follows the standard MCP protocol and can work with any MCP-compatible application or AI assistant. Simply configure your tool to connect to the Swift MCP server using one of the methods above.

Compatible Applications Include:

• Claude Desktop
• VS Code with MCP extensions
• Cursor
• Continue
• Zed
• Sourcegraph Cody
• Any custom MCP client implementation.

💡 Pro Tips for Better Integration

Claude Desktop Optimization

• Create a custom project in Claude with instructions about how you use Things 3 and organize areas, projects, tags, etc.
• Tell Claude what information to include when creating tasks (e.g., relevant details in task descriptions).
• Combine with calendar MCP servers to let Claude block time for tasks and create todos from calendar events.

Multi-Client Usage

• Use TCP mode to connect multiple clients simultaneously.
• Keep TaskNote Bridge app open to monitor all MCP activity in real-time.
• Check the app logs if you encounter any issues with tool calls.

Advanced Workflows

• "Evaluate my current todos using the Eisenhower matrix"
• "Help me conduct a GTD-style weekly review using Things"
• "Create a project plan for [project name] with subtasks and deadlines"
• "Analyze my task completion patterns and suggest improvements"

Project Structure

TaskNote Bridge.app/          # The macOS Swift application
├── Contents/
│   ├── MacOS/                # Native Swift executable containing MCP server
│   │   └── TaskNote Bridge   # Main app with embedded MCP server
│   ├── Resources/            # Application resources
│   └── Info.plist            # App bundle configuration
├── TaskNote Bridge.xcodeproj/ # Xcode project
├── SwiftMCPServer.swift      # Core MCP server implementation
├── ThingsIntegration.swift   # Things 3 integration layer
├── NotesIntegration.swift    # Apple Notes integration layer
└── README.md                 # This documentation

Available Tools

List Views

• get-inbox - Get todos from Inbox.
• get-today - Get todos due today.
• get-upcoming - Get upcoming todos.
• get-anytime - Get todos from Anytime list.
• get-someday - Get todos from Someday list.
• get-logbook - Get completed todos.
• get-trash - Get trashed todos.

Basic Operations

• get-todos - Get todos, optionally filtered by project.
• get-projects - Get all projects.
• get-areas - Get all areas.

Tag Operations

• get-tags - Get all tags.
• get-tagged-items - Get items with a specific tag.

Search Operations

• search-todos - Simple search by title/notes.
• search-advanced - Advanced search with multiple filters.
• open-todo - Search for a todo by title and open it in Things app.

Time-based Operations

• get-recent - Get recently created items.

Tool Parameters

get-todos

• project_uuid (optional) - Filter todos by project.
• include_items (optional, default: true) - Include checklist items.

get-projects / get-areas / get-tags

• include_items (optional, default: false) - Include contained items.

search-advanced

• status - Filter by status (incomplete/completed/canceled).
• start_date - Filter by start date (YYYY-MM-DD).
• deadline - Filter by deadline (YYYY-MM-DD).
• tag - Filter by tag.
• area - Filter by area UUID.
• type - Filter by item type (to-do/project/heading).

get-recent

• period - Time period (e.g., '3d', '1w', '2m', '1y').

open-todo

• title - Title or partial title of the todo to search for and open.

notes-open

• title - Exact title of the note to open in Apple Notes.

Troubleshooting

Connection Issues

Claude Desktop

• Check config file: Ensure the JSON configuration is valid and properly formatted.
• Verify file paths: Make sure /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh exists.
• Restart Claude: Completely quit and restart Claude Desktop after configuration changes.
• Check logs: Review Claude logs at ~/Library/Logs/Claude/mcp*.log.

TCP Connection Problems

• App running: Ensure TaskNote Bridge app is running with TCP server started.
• Port availability: Check if port 8000 is available with lsof -i :8000.
• Firewall settings: Verify macOS firewall allows local connections.
• Try different port: Change port in TaskNote Bridge app settings if needed.

Stdio Connection Issues

• Script permissions: Verify script is executable: ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh.
• Direct testing: Test the script in Terminal to ensure it works.
• Things 3 URLs: Ensure "Enable Things URLs" is turned on in Things 3 → Settings → General.

Tool Execution Issues

The server includes comprehensive error handling for:

• Invalid UUIDs and malformed requests.
• Missing required parameters.
• Things 3 database access errors.
• Apple Notes AppleScript execution errors.
• Data formatting and serialization errors.

All errors are logged with descriptive messages. To review MCP logs:

# Follow Claude Desktop logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Check TaskNote Bridge app logs
# Open TaskNote Bridge app and view the built-in log viewer

# Test server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh

Common Error Solutions

"Permission denied" errors

• Run: chmod +x /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh.
• Grant necessary permissions to TaskNote Bridge app in System Preferences → Security & Privacy.

"Things 3 not responding" errors

• Ensure Things 3 is installed and has been launched at least once.
• Check that "Enable Things URLs" is enabled in Things 3 settings.
• Try restarting Things 3.

"Apple Notes access denied" errors

• Grant TaskNote Bridge permission to control Apple Notes in System Preferences → Security & Privacy → Automation.
• Ensure Apple Notes app is not restricted by any security software.

🚨 Troubleshooting

Claude Desktop Connection Issues

"Request timed out" / Server not responding

If Claude Desktop shows timeout errors or doesn't receive responses:

❌ Incorrect Configuration (causes timeouts):

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "nc",
            "args": ["localhost", "8000"]
        }
    }
}

✅ Correct Configuration:

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

Why this matters:

• Claude Desktop expects stdio-based communication (launching a subprocess).
• The nc localhost 8000 approach tries to use TCP through netcat, which doesn't properly handle MCP protocol initialization.
• The stdio script provides proper JSON-RPC message handling that Claude Desktop requires.

To fix:

1. Update your Claude Desktop configuration to use the stdio script.
2. Restart Claude Desktop.
3. The connection should now work without timeouts.

Verify the server works

Test the stdio server directly:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | /path/to/tasknote-bridge/launch_swift_mcp_stdio.sh

You should see an immediate response like:

{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"things-mcp-swift","version":"1.0.0"},"protocolVersion":"2024-11-05","capabilities":{"tools":{}}}}