anytype-grpc

anytype-grpc

Edit Anytype blocks, layouts, and views from Python or MCP, over its internal gRPC API.

Why this exists

Every other Anytype library wraps the official Local HTTP API, which covers search, object creation, properties, and markdown. The block tree, layouts, set and query views, and covers live a layer deeper.

This library talks to that layer: the internal gRPC service (anytype-heart's ClientCommands) that the Anytype desktop app uses for every action. It can do everything the desktop UI does, programmatically:

• create, move, delete, and restyle any block (text, headers, toggles, checkboxes, code, tables, links)
• build column and grid layouts
• create and edit sets and queries, switch view types (table, gallery, list, kanban, calendar), and choose which properties show and which relation provides the cover
• set object covers and icons, upload files and images
• create and edit types, relations, and templates
• search, and read the full block tree of any object

All 332 RPC methods are reachable. The common, fiddly ones have ergonomic helpers.

How it works

The desktop app runs a local helper process that serves gRPC on a loopback port. This library auto-discovers that port, authenticates with a session token derived from your account, and speaks the same protocol the UI speaks. The real Anytype engine does all the work, and this library is a thin remote control over it.

Install

This is not on PyPI yet, so install it from source.

Straight from GitHub:

pip install "anytype-grpc[mcp] @ git+https://github.com/cengizozel/anytype-grpc.git"

Or clone and install editable, which is handy for reading or changing the code:

git clone https://github.com/cengizozel/anytype-grpc.git
cd anytype-grpc
pip install -e ".[mcp]"

Drop the [mcp] extra if you only want the client without the MCP server. Requires the Anytype desktop app to be running on the same machine.

Authenticate

The full gRPC surface needs a session token derived from your account. Mint one from your recovery phrase (the words you saved when you set up Anytype):

python -m anytype_grpc.auth

It reads the phrase from hidden input, never writes it to disk, and prints a token. Put that token in your environment:

export ANYTYPE_TOKEN="<the token>"

The token grants complete access to your local vault. Treat it like a password and never commit it.

Quick start

from anytype_grpc import Anytype

at = Anytype()                       # auto-discovers the port, reads ANYTYPE_TOKEN
print(at.app_version())              # works without a token

space = "your-space-id"
results = at.search("project", space_id=space)   # full-text search
page = results[0]["id"]

# read the whole object (blocks + details)
obj = at.objects.show(page)

# edit the block tree (namespaces group the full API by domain)
at.blocks.add_header(page, "A new heading", level=2)
at.blocks.add_text(page, "some body text")

# set a property
at.objects.set_details(page, {"description": "edited by anytype-grpc"})

# make a set, turn it into a gallery, choose its columns
new_set = at.objects.create_set([type_id], details={"name": "My gallery"})
at.views.set_view_type(new_set, "Gallery")
at.views.set_visible_columns(new_set, ["name", "status"])

Two layers

1. Ergonomic namespaces group the full helper API by domain. Each is reached on the client:

• at.blocks blocks: text, headers, checkboxes, toggles, code, links, files, tables, grids
• at.objects objects: create, show, details, covers, icons, archive, import, export
• at.views set and query views: type, columns, covers, filters, sorts
• at.files files and images: upload, download, offload, usage
• at.types types, relations (properties), options, templates
• at.spaces spaces and account: list, create, info, invites, members
• at.query advanced search and live subscriptions

A few of the most common operations also have top-level shortcuts (at.search, at.get_object, at.add_block). See the docs for every method.

2. Generic access to every method. Anything the app can do is reachable, even if there is no hand-written helper:

# call any of the 332 RPC methods by name
resp = at.call("BlockListSetAlign", context_id=page, blockIds=[bid], align=1)

# build a request to fill in by hand when a method needs nested messages
req = at.new_request("ObjectSearch")
req.spaceId = space
req.fullText = "notes"
resp = at.call("ObjectSearch", req)

# resolve the request type for any method
print(at.request_type("ObjectCreateSet").DESCRIPTOR.full_name)

MCP server

This package also ships an MCP server, so AI assistants can drive Anytype through the same capabilities. It is a thin wrapper over the library. See docs/mcp.md for setup and the full tool reference.

anytype-grpc-mcp

Security

• Your recovery phrase and the session token grant full access to your local vault. Never commit them. Keep them in environment variables or a gitignored .env.
• The gRPC service listens only on loopback (127.0.0.1).
• Keep the desktop app updated.

Versioning

The internal gRPC API is private and can change between Anytype versions. The vendored protos are pinned to a specific Anytype version (see protos/). If you upgrade the desktop app, regenerate the bindings with scripts/gen_protos.sh against the matching anytype-heart tag.

License

MIT. The vendored protos are from anyproto/anytype-heart (MIT).