Anytype MCP Server

A comprehensive Model Context Protocol (MCP) server for seamless integration with the Anytype knowledge management platform. This server provides a complete set of tools for managing spaces, objects, properties, types, tags, and templates through the Anytype API.

🚀 Features

• Complete API Coverage: Full support for all Anytype API endpoints

• Space Management: Create, update, and manage Anytype spaces

• Object Operations: CRUD operations for objects with advanced search capabilities

• Property Management: Dynamic property creation and management

• Type System: Custom object types with full lifecycle management

• Tag Management: Organize content with tags and multi-select properties

• Template Support: Access and utilize Anytype templates

• Collection & List Operations: Manage collections and lists with proper view handling

• Modern Development: Built with Vite for fast development and optimized builds

• Package Management: Uses pnpm for efficient dependency management

• TypeScript Support: Fully typed for enhanced developer experience

• Modular Architecture: Clean, maintainable code structure

📋 Prerequisites

• Node.js 18.0.0 or higher

• pnpm 8.0.0 or higher (recommended) or npm

• Anytype application running locally

• Valid Anytype API key

🛠️ Installation

Option 1: Local Installation (Recommended - pnpm)

1. Install pnpm globally (if not already installed)

   npm install -g pnpm

2. Clone the repository

   git clone <repository-url> cd my-mcp-anytype

3. Install dependencies

   pnpm install

4. Configure environment variables

   # Copy the example file cp .env.example .env # Edit .env with your actual values # ANYTYPE_API_KEY=your-actual-api-key # ANYTYPE_BASE_URL=http://localhost:31009

5. Build the project

   pnpm build

6. Start the server

   pnpm start

Option 2: Local Installation (npm)

1. Clone the repository

   git clone <repository-url> cd my-mcp-anytype

2. Install dependencies

   npm install

3. Configure environment variables

   # Copy the example file cp .env.example .env # Edit .env with your actual values # ANYTYPE_API_KEY=your-actual-api-key # ANYTYPE_BASE_URL=http://localhost:31009

4. Build the project

   npm run build

5. Start the server

   npm start

Option 3: Docker Installation

1. Clone the repository

   git clone <repository-url> cd my-mcp-anytype

2. Configure environment variables

   # Copy and edit the environment file cp .env.example .env # Edit .env with your actual Anytype API key

3. Run with Docker Compose

   # Build and start the container docker-compose up -d # View logs docker-compose logs -f # Stop the container docker-compose down

4. Or run with Docker directly

   # Build the image docker build -t anytype-mcp . # Run the container docker run -d \ --name anytype-mcp-server \ --network host \ --env-file .env \ anytype-mcp

⚙️ Configuration

Environment Variables

Getting Your API Key

1. Open Anytype application

2. Navigate to Settings → Developer

3. Generate or copy your API key

4. Add it to your .env file

🔧 Vite & Modern Development Tools

This project uses modern development tools for optimal developer experience:

Vite Benefits

• ⚡ Lightning Fast: Instant server start and HMR

• 📦 Optimized Builds: Efficient bundling with Rollup

• 🔧 Zero Config: Works out of the box with sensible defaults

• 🎯 TypeScript Native: First-class TypeScript support

Available Scripts

pnpm Advantages

• 💾 Disk Efficient: Saves up to 50% disk space

• ⚡ Faster Installs: Up to 2x faster than npm

• 🔒 Strict: Better dependency resolution

• 🌐 Monorepo Ready: Built-in workspace support

🏷️ Tags Management

Enhanced Tag Support

The MCP now includes enhanced tag management with automatic validation and processing:

• ✅ Automatic Tag Validation: Tags are validated when creating/updating objects

• ✅ Improved Error Handling: Clear error messages for invalid tag assignments

• ✅ Better Documentation: Comprehensive examples and usage patterns

• ✅ Consistent API: Standardized property_id usage across all tag operations

Quick Tag Workflow

1. Create tags for a multi_select property:

   anytype_create_tag --space_id="space123" --name="Urgent" --color="red" --property_id="prop456"

2. Create object with tags:

   anytype_create_object \ --space_id="space123" \ --name="My Task" \ --properties='[{"key":"labels","multi_select":["tag_id_1","tag_id_2"]}]'

3. Update object with new tags:

   anytype_update_object \ --space_id="space123" \ --object_id="obj789" \ --properties='[{"key":"status","select":"completed_tag_id"}]'

For complete tag usage examples, see TAGS_USAGE.md.

🔄 Special Object Update Method

Important: Object Recreation Pattern

Due to Anytype API behavior, updating object content requires a special approach:

The Challenge

When updating objects in Anytype, simply patching properties may not reflect changes immediately in the UI due to caching and synchronization mechanisms.

The Solution: Recreation Pattern

Implementation Example

When to Use This Pattern

• ✅ Content Updates: When changing object text, descriptions, or main content

• ✅ Property Changes: When modifying custom properties

• ✅ Type Changes: When changing object type

• ❌ Simple Metadata: For basic metadata updates, regular PATCH may suffice

Important Considerations

• ID Changes: The object will get a new ID after recreation

• References: Update any references to the old object ID

• Permissions: Ensure proper permissions for delete/create operations

• Backup: Consider backing up important objects before updates

Space Management

Object Operations

Property Management

Type Management

Tag Management

Template Operations

Collection & List Operations

🏗️ Project Structure

🔌 API Endpoints

This MCP server interfaces with the following Anytype API endpoints:

Spaces

• GET /v1/spaces - List spaces

• GET /v1/spaces/{id} - Get space

• POST /v1/spaces - Create space

• PATCH /v1/spaces/{id} - Update space

• GET /v1/spaces/{id}/members - List members

Objects

• POST /v1/search - Global search

• POST /v1/spaces/{id}/search - Space search

• GET /v1/spaces/{id}/objects - List objects

• GET /v1/spaces/{id}/objects/{objectId} - Get object

• POST /v1/spaces/{id}/objects - Create object

• PATCH /v1/spaces/{id}/objects/{objectId} - Update object

• DELETE /v1/spaces/{id}/objects/{objectId} - Delete object

Properties

• GET /v1/spaces/{id}/properties - List properties

• POST /v1/spaces/{id}/properties - Create property

• PATCH /v1/spaces/{id}/properties/{propertyId} - Update property

• DELETE /v1/spaces/{id}/properties/{propertyId} - Delete property

Types

• GET /v1/spaces/{id}/types - List types

• POST /v1/spaces/{id}/types - Create type

• PATCH /v1/spaces/{id}/types/{typeId} - Update type

• DELETE /v1/spaces/{id}/types/{typeId} - Delete type

Templates

• GET /v1/spaces/{id}/types/{typeId}/templates - List templates

• GET /v1/spaces/{id}/types/{typeId}/templates/{templateId} - Get template

🐳 Docker Support

Why Docker?

• Consistent Environment: Ensures the same runtime across different systems

• Easy Deployment: Simple containerized deployment

• Isolation: Runs in an isolated environment

• Scalability: Easy to scale and manage

Docker Configuration

The project includes:

• Dockerfile: Multi-stage build with security best practices

• docker-compose.yml: Complete orchestration setup

• .dockerignore: Optimized build context

• Health checks and resource limits

Network Considerations

Host Network Mode (Recommended):

This allows the container to access Anytype running on the host machine.

Bridge Network Mode (Alternative): If Anytype is also containerized, use a custom network:

Environment Variables in Docker

The container uses the same environment variables as the local installation:

• ANYTYPE_API_KEY: Your API key

• ANYTYPE_BASE_URL: Defaults to http://host.docker.internal:31009 in Docker

🚀 Development

Available Scripts

Docker Development

Adding New Features

1. Define tool schema in the appropriate tools/*.ts file

2. Implement handler in the corresponding handlers/*.ts file

3. Register tool in src/index.ts

4. Update documentation as needed

Code Style

• TypeScript with strict type checking

• Modular architecture with separation of concerns

• Consistent error handling with MCP error types

• Comprehensive input validation

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

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

🆘 Support

If you encounter any issues or have questions:

1. Check the Issues page for existing solutions

2. Create a new issue with detailed information

3. Include your environment details and error messages

🙏 Acknowledgments

• Anytype for the amazing knowledge management platform

• Model Context Protocol for the integration framework

• The open-source community for continuous inspiration

Made with ❤️ for the Anytype community