MCP tools reference
The cerebro MCP server provides 7 tools that allow AI assistants to query cortex
data. All tools are thin wrappers over cerebro-core query operations.
Tool list
list_projects
List all tracked projects with their metadata.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
active_only | boolean | No | If true, only return active projects. Default: true |
Returns: array of project objects with name, repo_path, active status, and last activity timestamp.
read_project
Read combined generated and manual content for a specific project.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Project name to read |
Returns: combined content including project config, sessions, commits, TODOs, and manual notes, covering status, next actions, and journal excerpts.
read_journal
Read a journal entry for a specific date.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
date | string | Yes | Date in YYYY-MM-DD format |
Returns: journal entry content for the specified date, or empty if no entry exists.
read_today
Read today’s journal entry.
Parameters: none
Returns: today’s journal entry content, or empty if no entry exists for today.
read_intent
Read intent/goals for a specific period.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
period | string | Yes | Period type: daily, weekly, monthly, or yearly |
identifier | string | Yes | Period identifier, such as 2026-04-15 for daily, 2026-W15 for weekly, 2026-04 for monthly, 2026 for yearly |
Returns: intent/goals content for the specified period.
search_todos
Search TODO comments across all projects.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
keyword | string | No | Filter by keyword: TODO, Needs Fixing, Hack, or Placeholder |
project | string | No | Filter by project name |
Returns: array of TODO items with path, line number, keyword type, and comment text.
get_stats
Get overall cortex statistics.
Parameters: none
Returns: statistics including project count, total TODO count, session count, commit count, and recent activity metrics.
Configuration
The MCP server reads CORTEX_PATH to locate the cortex data directory. If unset, it falls back to ~/Projects/cortex. Most users with the default layout don’t need to set it.
Start it from any MCP-compliant client. The example below uses OpenCode:
{
"mcpServers": {
"cerebro": {
"command": "cerebro",
"args": ["mcp"],
"env": {
"CORTEX_PATH": "/path/to/cortex"
}
}
}
}
Configure the command and environment variables according to your client’s documentation. The server speaks standard MCP (JSON-RPC) and has no dependency on any specific client.
Command-line tool equivalents
Each MCP tool has a corresponding command-line tool command that returns the same data as human-readable output. If you don’t use an AI assistant, the command-line tool commands give you direct access to your cortex from the terminal.
| MCP tool | Command-line tool equivalent |
|---|---|
list_projects | cerebro projects list |
read_project | cerebro projects read <name> |
read_journal | cerebro journal read <date> |
read_today | cerebro journal today |
read_intent | cerebro intent <period> <identifier> |
search_todos | cerebro todos |
get_stats | cerebro stats |