MCP Planfix

🚀 Planfix MCP Server

Integrate the business process management system Planfix with the Model Context Protocol (MCP) for use with Claude and other AI assistants.

🚀 Quick Start

This server integrates Planfix with the Model Context Protocol (MCP), enabling seamless interaction with AI assistants. After setup, you can perform various tasks such as task creation, information search, and analytics retrieval.

✨ Features

🛠️ Tools

• Task Management: Create, search, and update task statuses.
• Project Management: Create new projects.
• Contacts: Add new contacts to the CRM.
• Analytics: Obtain reports on time, finances, and tasks.
• Comments: Add comments to tasks.

📊 Resources

• Project List: Active projects with the number of tasks.
• Dashboard Summary: Current state of the workspace.
• Task Details: Detailed information about specific tasks.
• Recent Contacts: Recently added contacts.
• Reports: Pre - generated reports.

💡 Prompts

• Project Analysis: Template for analyzing the project status.
• Weekly Reports: Template for creating reports.
• Sprint Planning: Template for task planning.

📦 Installation

Requirements

• Python 3.8+
• uv (recommended) or pip
• A Planfix account with API access

1. Clone the repository and install dependencies

git clone <repository-url>
cd planfix-mcp-server

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

2. Configure API keys

Get an API key in your Planfix account:

1. Go to Settings → API.
2. Create a new API key.

Create a .env file:

cp .env.example .env

Fill in the .env file:

PLANFIX_ACCOUNT=your-account-name
PLANFIX_API_KEY=your-api-key

3. Testing

# Run with command - line arguments
python -m src.planfix_server --account your-account --api-key your-api-key

# Run in debug mode
python -m src.planfix_server --debug

# View help
python -m src.planfix_server --help

# Run with environment variables (from the .env file)
python -m src.planfix_server

💻 Usage Examples

Basic Usage

After installation, you can use the following commands:

Task Creation

Create a task "Prepare a presentation" with the description "Presentation for client XYZ" and priority HIGH

Information Search

Find all tasks for the project "Website Development"

Analytics Retrieval

Show the time report for the last month

Project Management

Create a project "New Marketing Campaign" with the description "Q1 2024 campaign"

Advanced Usage

You can use Planfix in Cursor after configuration:

Find all active tasks for the project "Website Development"

Show details of the contact with ID 123

Create a report on all overdue tasks

📚 Documentation

Command - Line Arguments

The server supports the following command - line arguments:

Usage examples:

# Full configuration via arguments
uv run python -m src.planfix_server --account mycompany --api-key abc123

# Run in debug mode
uv run python -m src.planfix_server --debug

# Combine with environment variables
export PLANFIX_ACCOUNT=mycompany
uv run python -m src.planfix_server --api-key abc123

Environment Variables

Configuration in Cursor

Cursor supports MCP servers starting from version 0.42+. To connect:

1. Open Cursor settings: Cmd/Ctrl + ,
2. Find the "MCP Servers" section or add the configuration to the settings file.
3. Add the server configuration:

Using uvx:

{
  "mcp.servers": {
    "planfix": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/your-repo/planfix-mcp@main",
        "planfix-server",
        "--account", "your-account-name",
        "--api-key", "your-api-key"
      ]
    }
  }
}

Or with environment variables:

{
  "mcp.servers": {
    "planfix": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/your-repo/planfix-mcp@main",
        "planfix-server"
      ],
      "env": {
        "PLANFIX_ACCOUNT": "your-account-name",
        "PLANFIX_API_KEY": "your-api-key"
      }
    }
  }
}

4. Alternative method via .cursorrules:

Create a .cursorrules file at the root of your project:

MCP Server: Planfix Integration

This project uses a Planfix MCP server for task and project management.

Available tools:
- search_tasks: Find tasks by query, project, assignee, or status
- search_contacts: Search for contacts and companies  
- get_contact_details: Get detailed information about a contact
- list_employees: Get list of employees
- list_files: Get files associated with tasks/projects
- list_comments: Get comments for tasks/projects
- list_reports: Get available reports
- list_processes: Get business processes

Server configuration:
- Command: uvx --from git+https://github.com/your-repo/planfix-mcp@main planfix-server
- Requires PLANFIX_ACCOUNT, PLANFIX_API_KEY environment variables

Use these tools to help with project management, task tracking, and CRM operations.

5. Restart Cursor to apply the changes.
6. Check the connection: Available Planfix tools should appear in the Cursor chat.

Troubleshooting in Cursor

• Check paths: Use absolute paths to files.
• Environment variables: Ensure all API keys are correctly specified.
• Logs: Check the output in the Cursor developer console (Cmd/Ctrl + Shift + I).
• Version: Make sure you are using Cursor 0.42 or later.

🔧 Technical Details

Project Structure

planfix-mcp-server/
├── src/
│   ├── planfix_server.py          # Main MCP server
│   ├── planfix_api.py             # API client for Planfix
│   ├── config.py                  # Configuration
│   └── utils.py                   # Utility functions
├── tests/
│   ├── test_server.py             # Server tests
│   ├── test_api.py                # API tests
│   └── conftest.py                # pytest configuration
├── examples/
│   ├── basic_usage.py             # Usage examples
│   └── advanced_workflows.py     # Complex scenarios
├── docs/
│   ├── api_reference.md           # API reference
│   └── troubleshooting.md         # Troubleshooting
├── .env.example                   # Configuration example
├── requirements.txt               # Dependencies
├── pyproject.toml                # Project configuration
└── README.md                      # Documentation

Running Tests

# All tests
uv run pytest

# With code coverage
uv run pytest --cov=src

# Only fast tests
uv run pytest -m "not slow"

Linting and Formatting

# Code formatting
uv run ruff format

# Style check
uv run ruff check

# Type check
uv run mypy src/

API Reference

Detailed documentation for all available tools, resources, and prompts can be found in docs/api_reference.md.

Troubleshooting

Common issues and their solutions are described in docs/troubleshooting.md.

📄 License

This project is under the MIT License - see the LICENSE file for details.

Support

• GitHub Issues: For bug reports and feature requests.
• MCP Documentation: https://modelcontextprotocol.io/

Changelog

v1.0.1 (2024 - 12 - 23)

• Improved command - line argument handling using argparse.
• Added --help, --version, and --debug options.
• Removed emojis and Markdown formatting from tool output.
• Simplified data return via model_dump() for better integration.
• Removed the dependency on PLANFIX_USER_KEY (only PLANFIX_ACCOUNT and PLANFIX_API_KEY are required).
• Updated the Cursor configuration to use uvx and git+repo@main.
• Removed the Claude Desktop section from the documentation.

v1.0.0 (2024 - 12 - 23)

• First release.
• Basic operations on tasks and projects.
• Integration with Planfix analytics.
• Support for contact management.