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)

Install pnpm globally (if not already installed)
```
npm install -g pnpm
```

Clone the repository

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

Install dependencies
```
pnpm install
```

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

Build the project
```
pnpm build
```
Start the server
```
pnpm start
```

Option 2: Local Installation (npm)

Clone the repository

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

Install dependencies
```
npm install
```

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

Build the project
```
npm run build
```
Start the server
```
npm start
```

Option 3: Docker Installation

Clone the repository

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

Configure environment variables

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

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

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

Variable	Description	Default	Required
`ANYTYPE_API_KEY`	Your Anytype API key	-	✅
`ANYTYPE_BASE_URL`	Anytype API base URL	`http://localhost:31009`	❌
`MCP_PORT`	Port for MCP server	`3000`	❌
`LOG_LEVEL`	Logging level	`info`	❌
`REQUEST_TIMEOUT`	API request timeout (ms)	`30000`	❌

Getting Your API Key

Open Anytype application
Navigate to Settings → Developer
Generate or copy your API key
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

# Development
pnpm dev          # Start development server with hot reload
pnpm build        # Build for production using Vite
pnpm preview      # Preview production build locally
pnpm start        # Start the built MCP server

# Utilities
pnpm clean        # Clean build artifacts
pnpm type-check   # Run TypeScript type checking
pnpm prepare      # Pre-publish preparation

# Docker
docker-compose up --build  # Build and run with Docker

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

Create tags for a multi_select property:

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

Create object with tags:

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

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

// Instead of simple update:
// PATCH /v1/spaces/{spaceId}/objects/{objectId}

// Use this pattern:
1. Get current object data
2. Delete the existing object
3. Create new object with updated content
4. Return new object ID

Implementation Example

async function updateObjectContent(spaceId: string, objectId: string, updates: any) {
  // 1. Get current object
  const currentObject = await getObject(spaceId, objectId);
  
  // 2. Merge updates with current data
  const updatedData = {
    ...currentObject,
    ...updates,
    // Preserve important metadata
    type: currentObject.type,
    createdDate: currentObject.createdDate
  };
  
  // 3. Delete current object
  await deleteObject(spaceId, objectId);
  
  // 4. Create new object with updated content
  const newObject = await createObject(spaceId, updatedData);
  
  return newObject;
}

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

Tool	Description
`anytype_list_spaces`	List all available spaces
`anytype_get_space`	Get specific space details
`anytype_create_space`	Create a new space
`anytype_update_space`	Update existing space
`anytype_list_members`	List space members
`anytype_get_member`	Get specific member details

Object Operations

Tool	Description
`anytype_search_objects`	Search objects with advanced filters
`anytype_list_objects`	List objects in a space
`anytype_get_object`	Get specific object details
`anytype_create_object`	Create new object
`anytype_update_object`	Update existing object
`anytype_delete_object`	Delete (archive) object

Property Management

Tool	Description
`anytype_list_properties`	List all properties in a space
`anytype_get_property`	Get specific property details
`anytype_create_property`	Create new property
`anytype_update_property`	Update existing property
`anytype_delete_property`	Delete property

Type Management

Tool	Description
`anytype_list_types`	List all object types
`anytype_get_type`	Get specific type details
`anytype_create_type`	Create new object type
`anytype_update_type`	Update existing type
`anytype_delete_type`	Delete object type

Tag Management

Tool	Description
`anytype_list_tags`	List tags for a property
`anytype_get_tag`	Get specific tag details
`anytype_create_tag`	Create new tag
`anytype_update_tag`	Update existing tag
`anytype_delete_tag`	Delete tag

Template Operations

Tool	Description
`anytype_list_templates`	List templates for a type
`anytype_get_template`	Get specific template details

Collection & List Operations

Tool	Description
`anytype_add_to_collection`	Add object to collection
`anytype_remove_from_collection`	Remove object from collection
`anytype_get_list_views`	Get available views for a list
`anytype_get_list_objects`	Get objects from a list view

🏗️ Project Structure

src/
├── index.ts                 # Main server entry point
├── startup-info.ts          # Server startup information
├── utils.ts                 # Utility functions and API helpers
├── handlers/                # Request handlers
│   ├── spaces.ts           # Space and member operations
│   ├── objects.ts          # Object CRUD operations
│   ├── properties.ts       # Property management
│   └── types-tags.ts       # Types, tags, and templates
└── tools/                   # MCP tool definitions
    ├── spaces.ts           # Space tool schemas
    ├── objects.ts          # Object tool schemas
    ├── properties.ts       # Property tool schemas
    ├── types.ts            # Type tool schemas
    ├── tags.ts             # Tag tool schemas
    ├── templates.ts        # Template tool schemas
    ├── lists.ts            # List tool schemas
    └── schemas.ts          # Common schemas

🔌 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):

network_mode: host

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:

networks:
  - anytype-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

npm run build    # Compile TypeScript to JavaScript
npm start        # Start the MCP server
npm run dev      # Development mode with tsx
npm run prepare  # Pre-publish build step

Docker Development

# Development with Docker
docker-compose -f docker-compose.yml up --build

# View logs in real-time
docker-compose logs -f anytype-mcp

# Execute commands in container
docker-compose exec anytype-mcp sh

Adding New Features

Define tool schema in the appropriate tools/*.ts file
Implement handler in the corresponding handlers/*.ts file
Register tool in src/index.ts
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

Check the Issues page for existing solutions
Create a new issue with detailed information
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

Anytype MCP Server

🚀 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)

Install pnpm globally (if not already installed)
```
npm install -g pnpm
```

Clone the repository

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

Install dependencies
```
pnpm install
```

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

Build the project
```
pnpm build
```
Start the server
```
pnpm start
```

Option 2: Local Installation (npm)

Clone the repository

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

Install dependencies
```
npm install
```

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

Build the project
```
npm run build
```
Start the server
```
npm start
```

Option 3: Docker Installation

Clone the repository

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

Configure environment variables

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

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

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

Variable	Description	Default	Required
`ANYTYPE_API_KEY`	Your Anytype API key	-	✅
`ANYTYPE_BASE_URL`	Anytype API base URL	`http://localhost:31009`	❌
`MCP_PORT`	Port for MCP server	`3000`	❌
`LOG_LEVEL`	Logging level	`info`	❌
`REQUEST_TIMEOUT`	API request timeout (ms)	`30000`	❌

Getting Your API Key

Open Anytype application
Navigate to Settings → Developer
Generate or copy your API key
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

# Development
pnpm dev          # Start development server with hot reload
pnpm build        # Build for production using Vite
pnpm preview      # Preview production build locally
pnpm start        # Start the built MCP server

# Utilities
pnpm clean        # Clean build artifacts
pnpm type-check   # Run TypeScript type checking
pnpm prepare      # Pre-publish preparation

# Docker
docker-compose up --build  # Build and run with Docker

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

Create tags for a multi_select property:

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

Create object with tags:

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

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

// Instead of simple update:
// PATCH /v1/spaces/{spaceId}/objects/{objectId}

// Use this pattern:
1. Get current object data
2. Delete the existing object
3. Create new object with updated content
4. Return new object ID

Implementation Example

async function updateObjectContent(spaceId: string, objectId: string, updates: any) {
  // 1. Get current object
  const currentObject = await getObject(spaceId, objectId);
  
  // 2. Merge updates with current data
  const updatedData = {
    ...currentObject,
    ...updates,
    // Preserve important metadata
    type: currentObject.type,
    createdDate: currentObject.createdDate
  };
  
  // 3. Delete current object
  await deleteObject(spaceId, objectId);
  
  // 4. Create new object with updated content
  const newObject = await createObject(spaceId, updatedData);
  
  return newObject;
}

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

Tool	Description
`anytype_list_spaces`	List all available spaces
`anytype_get_space`	Get specific space details
`anytype_create_space`	Create a new space
`anytype_update_space`	Update existing space
`anytype_list_members`	List space members
`anytype_get_member`	Get specific member details

Object Operations

Tool	Description
`anytype_search_objects`	Search objects with advanced filters
`anytype_list_objects`	List objects in a space
`anytype_get_object`	Get specific object details
`anytype_create_object`	Create new object
`anytype_update_object`	Update existing object
`anytype_delete_object`	Delete (archive) object

Property Management

Tool	Description
`anytype_list_properties`	List all properties in a space
`anytype_get_property`	Get specific property details
`anytype_create_property`	Create new property
`anytype_update_property`	Update existing property
`anytype_delete_property`	Delete property

Type Management

Tool	Description
`anytype_list_types`	List all object types
`anytype_get_type`	Get specific type details
`anytype_create_type`	Create new object type
`anytype_update_type`	Update existing type
`anytype_delete_type`	Delete object type

Tag Management

Tool	Description
`anytype_list_tags`	List tags for a property
`anytype_get_tag`	Get specific tag details
`anytype_create_tag`	Create new tag
`anytype_update_tag`	Update existing tag
`anytype_delete_tag`	Delete tag

Template Operations

Tool	Description
`anytype_list_templates`	List templates for a type
`anytype_get_template`	Get specific template details

Collection & List Operations

Tool	Description
`anytype_add_to_collection`	Add object to collection
`anytype_remove_from_collection`	Remove object from collection
`anytype_get_list_views`	Get available views for a list
`anytype_get_list_objects`	Get objects from a list view

🏗️ Project Structure

src/
├── index.ts                 # Main server entry point
├── startup-info.ts          # Server startup information
├── utils.ts                 # Utility functions and API helpers
├── handlers/                # Request handlers
│   ├── spaces.ts           # Space and member operations
│   ├── objects.ts          # Object CRUD operations
│   ├── properties.ts       # Property management
│   └── types-tags.ts       # Types, tags, and templates
└── tools/                   # MCP tool definitions
    ├── spaces.ts           # Space tool schemas
    ├── objects.ts          # Object tool schemas
    ├── properties.ts       # Property tool schemas
    ├── types.ts            # Type tool schemas
    ├── tags.ts             # Tag tool schemas
    ├── templates.ts        # Template tool schemas
    ├── lists.ts            # List tool schemas
    └── schemas.ts          # Common schemas

🔌 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):

network_mode: host

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:

networks:
  - anytype-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

npm run build    # Compile TypeScript to JavaScript
npm start        # Start the MCP server
npm run dev      # Development mode with tsx
npm run prepare  # Pre-publish build step

Docker Development

# Development with Docker
docker-compose -f docker-compose.yml up --build

# View logs in real-time
docker-compose logs -f anytype-mcp

# Execute commands in container
docker-compose exec anytype-mcp sh

Adding New Features

Define tool schema in the appropriate tools/*.ts file
Implement handler in the corresponding handlers/*.ts file
Register tool in src/index.ts
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

Check the Issues page for existing solutions
Create a new issue with detailed information
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