Things MCP Server: Task Management Integration with Claude Desktop

Overview: What is Things MCP Server?

The Things MCP Server enables seamless interaction between Claude Desktop and the Things app, empowering users to leverage natural language processing (NLP) capabilities for task management. This server leverages the Things.py library and the Things URL Scheme to provide robust features such as task creation, analysis, project management, and more.

Core Features & MCP Capabilities

The Things MCP Server supports a wide range of capabilities, including:

• Natural Language Task Creation: Ask Claude to create tasks with all details in natural language.
• Smart Task Analysis: Get insights into your projects and productivity patterns.
• GTD & Productivity Workflows: Let Claude help you implement productivity systems like the Getting Things Done (GTD) method.
• Seamless Integration: Works directly with your existing Things 3 data, ensuring a frictionless user experience.

MCP Architecture & Protocol Implementation

The server is built on the Model Context Protocol (MCP), which provides a standardized way for AI applications to interact with various tools and data sources. The implementation involves two key components:

1. Base MCP Server: things_server.py - A traditional implementation that uses basic MCP server patterns.
2. FastMCP Server: things_fast_server.py - A modern implementation using the FastMCP pattern for cleaner, more maintainable code with decorator-based tool registration.

Getting Started with Installation

Option 1: Install from PyPI (Recommended)

Prerequisites

• Python 3.12+
• Claude Desktop
• Things 3 ("Enable Things URLs" must be turned on in Settings -> General)

Installation

pip install things-mcp

Or using uv:

uv pip install things-mcp

Running the Server

After installation, you can run the server directly:

things-mcp

Option 2: Manual Installation

Prerequisites

• Python 3.12+
• Claude Desktop
• Things 3 ("Enable Things URLs" must be turned on in Settings -> General)

Step 1: Install uv

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal afterwards.

Step 2: Clone this Repository

git clone https://github.com/hald/things-mcp
cd things-mcp

Step 3: Set Up Python Environment and Dependencies

uv venv
uv pip install -r pyproject.toml

Step 4: Configure Things Authentication Token

Run the configuration tool to set up your Things authentication token:

python configure_token.py

This will guide you through the process of configuring your Things authentication token, which is required for the MCP server to interact with your Things app.

Step 5: Integrate with Claude Desktop

Edit the mcp configuration in your ~/.config/Claude/config.json:

{
  "mcpServers": {
    "things": {
      "command": "uv",
      "args": ["-y", "./path/to/things_server.py"],
      "env": {
        "TOKEN": "<YOUR-TOKEN>"
      }
    }
  }
}

Key Use Cases in AI Workflows

1. Task Creation and Management

   Users can create tasks using natural language inputs, such as:

   Claude: Reminder: "Book flight to NYC for the conference" due by next Friday at 5 PM.
   

2. Data Analysis and Reporting

   Analyze project progress and productivity metrics with Claude:

   Claude: Provide a summary report of recent projects, focusing on those over budget.
   

Integration with MCP Clients

The Things MCP Server supports integration with multiple MCP clients, including:

MCP Client	Resources	Tools	Prompts
Claude Desktop	✅	✅	✅
Continue	✅	✅	✅
Cursor	❌	✅	❌

Performance & Compatibility Matrix

This table outlines the compatibility and performance of various tools with the Things MCP Server:

Tool/Library	Compatibility Status
Things	Full
Things.py	Full
FastMCP	Partial (FastMCP)

Advanced Configuration & Security

Logging

All errors are logged and returned with descriptive messages. To review the MCP logs from Claude Desktop, run:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Security Considerations

Ensure that your authentication token is kept secure by using environment variables or secure configuration files.

Frequently Asked Questions (FAQ)

1. How do I set up the Things MCP Server for use with Claude Desktop?

   • Follow the manual installation and configuration steps provided in the README to set up the server.

2. What tools are supported by the Things MCP Server?

   • The server supports the Things app, Things.py library, and other tools via the FastMCP pattern.

3. Can I use the Things MCP Server with both the standard implementation and the FastMCP version simultaneously?

   • Yes, you can run both implementations concurrently as long as they are configured separately in your mcp settings.

4. What is the best way to troubleshoot connectivity issues between Claude Desktop and the Things MCP Server?

   • Ensure that "Enable Things URLs" is checked in the Things app preferences, and use the server logs for detailed error reporting.

5. How do I update the Things MCP Server to a newer version if available from PyPI?

   • Use pip or uv pip commands to install the latest version:

     uv pip install --upgrade things-mcp
     

Development & Contribution Guidelines

The project uses pyproject.toml for dependency management and build configuration. Contributions are welcome, and developers can set up a development environment by following these steps:

1. Clone the Repository:

   git clone https://github.com/hald/things-mcp.git
   cd things-mcp
   

2. Set Up Virtual Environment with Dev Dependencies:

   uv venv
   uv pip install -e ".[dev]"
   

3. Run the Development Server:

   Test the server with:

   mcp dev things_fast_server.py
   # or
   mcp dev things_server.py
   

4. Build and Publish to PyPI:

   If you want to package the application for distribution, run:

   python -m build
   twine upload dist/*
   

MCP Ecosystem & Resources

For more information about the Model Context Protocol (MCP), visit:

• Model Context Protocol Documentation
• Things API Docs
• Claude Desktop Integration

Conclusion

The Things MCP Server is a powerful tool for enhancing AI application integration through the Model Context Protocol. By providing seamless task management and analysis capabilities, it empowers users to streamline their workflows and optimize productivity.

By integrating this server with Claude Desktop and other MCP clients, you can unlock advanced features and improve your overall workflow efficiency. Explore the documentation, contribute to the project, or dive into real-world use cases to see its full potential in action.