AFFiNE MCP server

AFFiNE MCP Server provides seamless integration with AFFiNE workspaces and documents through the Model Context Protocol. This server enables AI assistants to interact with self-hosted or cloud AFFiNE instances, offering comprehensive workspace and document management capabilities.

Requirements

• Node.js 18+
• AFFiNE instance (self-hosted or cloud)
• Valid AFFiNE credentials or access token

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

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)
[email protected]
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 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": "[email protected]",
        "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": "[email protected]", 
      "AFFINE_PASSWORD": "your_password"
    }
  }
}

Available Tools

Workspace Management

• 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

• 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

• 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

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

User Management

• 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

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

Notifications

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

Blob Storage

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

Advanced

• 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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect