Anytype MCP Server

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

🔄 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