Affine MCP Server

🚀 AFFiNE MCP Server

The AFFiNE MCP Server is a Model Context Protocol (MCP) server designed to seamlessly integrate with self - hosted or cloud AFFiNE instances. It offers a standardized interface for AI assistants to interact with AFFiNE workspaces and documents.

🚀 Quick Start

To quickly start using the AFFiNE MCP Server, follow the installation and configuration steps below. You'll need to have Node.js 18+ installed and access to an AFFiNE instance.

✨ Features

• Workspace Management: Create workspaces with initial documents (UI accessible).
• Document Operations: List, search, and manage documents.
• User Management: Handle authentication and profile management.
• Comments System: Perform full comment CRUD operations.
• Version History: Keep track of document history and enable recovery.
• Notifications: Read and manage notifications.

📦 Installation

# Clone the repository
git clone https://github.com/dawncr0w/affine-mcp-server.git
cd affine-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

📚 Documentation

Configuration

Create a .env file in the project root:

# AFFiNE server URL (required)
AFFINE_BASE_URL=https://your-affine-instance.com

# Authentication (choose one method):

# Option 1: Bearer Token (highest priority)
AFFINE_API_TOKEN=your_personal_access_token

# Option 2: Session Cookie
AFFINE_COOKIE=affine_session=xxx; affine_csrf=yyy

# Option 3: Email/Password (fallback)
AFFINE_EMAIL=your@email.com
AFFINE_PASSWORD=your_password

# Optional settings
AFFINE_GRAPHQL_PATH=/graphql  # Default: /graphql
AFFINE_WORKSPACE_ID=workspace-uuid  # Default workspace for operations

Authentication Priority

The server checks for authentication in this order:

1. Bearer Token (AFFINE_API_TOKEN) - Highest priority
2. Cookie (AFFINE_COOKIE)
3. Email/Password (AFFINE_EMAIL + AFFINE_PASSWORD) - Fallback

Quick Start with Different Tools

With Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "affine": {
      "command": "node",
      "args": ["/path/to/affine-mcp-server/dist/index.js"],
      "env": {
        "AFFINE_BASE_URL": "https://your-affine-instance.com",
        "AFFINE_EMAIL": "your@email.com",
        "AFFINE_PASSWORD": "your_password"
      }
    }
  }
}

With Codebase CLI (codex)

Add to your Codebase CLI configuration:

{
  "affine": {
    "command": "node",
    "args": ["/path/to/affine-mcp-server/dist/index.js"],
    "env": {
      "AFFINE_BASE_URL": "https://your-affine-instance.com",
      "AFFINE_EMAIL": "your@email.com", 
      "AFFINE_PASSWORD": "your_password"
    }
  }
}

Available Tools

Workspace Management (5 tools)

• list_workspaces - List all accessible workspaces
• get_workspace - Get workspace details
• create_workspace - Create workspace with initial document ✅
• update_workspace - Update workspace settings
• delete_workspace - Delete workspace permanently

Document Operations (6 tools)

• list_docs - List documents with pagination
• get_doc - Get document metadata
• search_docs - Search documents by keyword
• recent_docs - List recently updated documents
• publish_doc - Make document public
• revoke_doc - Revoke public access

Comments (5 tools)

• list_comments - List document comments
• create_comment - Create new comment
• update_comment - Update comment content
• delete_comment - Delete a comment
• resolve_comment - Resolve/unresolve comment

Version History (2 tools)

• list_histories - View document history
• recover_doc - Restore to previous version

User Management (4 tools)

• current_user - Get current user information
• sign_in - Sign in with email/password
• update_profile - Update user profile
• update_settings - Update user settings

Access Tokens (3 tools)

• list_access_tokens - List personal access tokens
• generate_access_token - Create new access token
• revoke_access_token - Revoke access token

Notifications (3 tools)

• list_notifications - Get notifications
• read_notification - Mark notification read
• read_all_notifications - Mark all notifications read

Blob Storage (3 tools)

• upload_blob - Upload file/blob
• delete_blob - Delete blob
• cleanup_blobs - Cleanup deleted blobs

Advanced (1 tool)

• apply_doc_updates - Apply CRDT updates to documents

Testing

# Run comprehensive tests
node test-comprehensive.mjs

# Test workspace creation
node test-fixed-workspace.mjs

Troubleshooting

Authentication Issues

1. Email/Password fails:

   • Ensure your AFFiNE instance allows password authentication.
   • Check network connectivity to the AFFiNE server.
   • Verify credentials are correct.

2. Cookie authentication:

   • Extract cookies from browser DevTools Network tab.
   • Look for affine_session cookie after logging in.
   • Include all relevant cookies in AFFINE_COOKIE.

3. Token authentication:

   • Generate token from AFFiNE user settings.
   • Ensure token hasn't expired.
   • Use the full token string in AFFINE_API_TOKEN.

Connection Issues

• Verify AFFINE_BASE_URL is accessible.
• Check if GraphQL endpoint is at /graphql (default).
• Ensure no firewall/proxy blocking connections.
• For self - hosted instances, verify CORS settings.

Security Considerations

• Never commit .env files containing credentials.
• Use environment variables in production.
• Rotate access tokens regularly.
• Always use HTTPS for AFFiNE connections.
• Store credentials in secure credential managers.

Version History

1.1.0 (2025-08-12)

• ✅ Fixed workspace creation with initial documents.
• Added 30+ tools for comprehensive AFFiNE management.
• Workspace creation now accessible in UI.
• Improved error handling and authentication.
• Simplified tool names for better usability.

1.0.0 (2025-08-12)

• Initial stable release.
• Basic workspace and document operations.
• Full authentication support.

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch.
3. Add tests for new features.
4. Ensure all tests pass.
5. Submit a Pull Request.

License

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

Support

For issues and questions:

• Open an issue on GitHub.
• Check AFFiNE documentation at https://docs.affine.pro.

Author

dawncr0w - GitHub

Acknowledgments

• Built for the AFFiNE knowledge base platform.
• Uses the Model Context Protocol specification.
• Powered by @modelcontextprotocol/sdk.