Anytype MCP

What anytype-mcp does

anytype-mcp lets MCP-compatible AI clients interact with Anytype through natural-language requests. It translates Anytype's OpenAPI description into MCP tools, covering global and space search, spaces and members, objects and lists, properties and tags, and types and templates. This supports workflows such as creating a space, adding task objects, assigning them, setting due dates, and collecting them in a list.

The server is intended for Anytype installations that expose the local API. It provides a conversational interface while retaining the API's request and response behavior, including errors, warnings, identifiers, and concurrency metadata.

How it works

At startup, the server discovers an OpenAPI document from the configured Anytype API. Standard startup checks the v2 document first and falls back to the older v1 document when the newer endpoint is unavailable. A specific OpenAPI URL can also be passed to select v1, v2, or another supplied document directly. Explicit URLs and local files are used as given rather than going through fallback discovery.

Discovery happens once for each MCP process. The parsed specification and HTTP client are reused for subsequent calls, so the process must be restarted after an Anytype update if newly available API operations should appear. MCP tool names are derived from the API operation identifiers, while the server preserves literal API values such as enum members and examples.

Setup and configuration

Install or run the package with npx:

npx -y @anyproto/anytype-mcp

Create an API key in Anytype under App Settings and API Keys. Pass it through OPENAPI_MCP_HEADERS as JSON containing an Authorization bearer value and an Anytype-Version value:

{
  "env": {
    "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
  }
}

The default API endpoint is http://127.0.0.1:31009. Set ANYTYPE_API_BASE_URL when using anytype-cli on port 31012 or another API location. The package can also be installed globally with npm and invoked as anytype-mcp.

Tools and capabilities

• Search across Anytype or within a space.
• Work with spaces and their members.
• Create and manage objects and lists.
• Use properties and tags.
• Work with types and templates.
• Inspect API schemas and operation details through generated schema tools.
• Create, update, and delete v1 objects, with compact receipts for successful mutations.
• Use etags to guard updates against changes made after a previous read.
• Use idempotency keys for safe retries of the same write request.

Limitations and notes

The server selects and parses one OpenAPI document per process. Startup fails for authentication problems, connection failures, API errors, or malformed OpenAPI JSON rather than silently choosing another specification.

For writes, expected_etag maps to If-Match; supply an etag from an earlier read when preventing accidental overwrites matters. request_key maps to Idempotency-Key on endpoints that support it. New writes receive generated idempotency keys when appropriate, but calls are not automatically retried. A globally configured idempotency key is rejected.

Some successful v1 mutations return a compact receipt instead of the complete object content. Read the object separately when its markdown, snippets, properties, icon, or full type information is needed. API failures are returned as MCP errors with available HTTP status, codes, messages, issues, and hints.