# Marvin MCP

Ask Marvin, Marvin Labs' equity research analyst, from Claude Desktop, Claude Code or any other MCP client. It runs locally over stdio and only calls the Marvin Labs public API (`/v1/responses`, `/v1/conversations`, `/v1/agent_results`) with your own API key. Conversations you start here show up in the Marvin app, and app conversations can be continued from here.

## Setup

You need:

1. **Access.** This is a private alpha version. Please email marvin@marvin-labs.com for access.
2. **An API key.** In the app: Account → API keys → Add new key.
3. **uv** (`curl -LsSf https://astral.sh/uv/install.sh | sh`).

Then, from the project you want Marvin in, run:

```bash
uvx --from git+https://github.com/Marvin-Labs/marvin-mcp marvin-mcp setup
```

It asks for your API key, checks that it works, and adds Marvin to the clients it finds. By default that is **this project only**:

| Client | `setup` (this project) | `setup --global` (all projects) |
|---|---|---|
| Claude Code | yes, private to you (not in `.mcp.json`) | yes |
| Codex, CLI and app | yes, in `.codex/config.toml`, kept out of git; Codex loads it once you trust the project | yes |
| Claude Desktop | no per-project setting | yes |
| ChatGPT desktop | no per-project setting | prints the values to paste into its settings |

Run it again to change the key. `--yes` sets up every client found without asking; `MARVIN_API_KEY` in the environment skips the key prompt; `--api-url` points the clients at another environment, such as stg.

### By hand

Any MCP client that starts local (stdio) servers works. The command is `uvx`, the arguments are `--refresh --from git+https://github.com/Marvin-Labs/marvin-mcp marvin-mcp`, and `MARVIN_API_KEY` goes in the server's environment. For example:

```bash
claude mcp add marvin --env MARVIN_API_KEY=ak_... \
  -- uvx --refresh --from "git+https://github.com/Marvin-Labs/marvin-mcp" marvin-mcp
codex mcp add marvin --env MARVIN_API_KEY=ak_... \
  -- uvx --refresh --from "git+https://github.com/Marvin-Labs/marvin-mcp" marvin-mcp
```

Claude Desktop on macOS does not see your shell's PATH, so give it the full path to `uvx` (`which uvx`).

`--refresh` fetches the latest version each time your client starts the server. To stay on one version instead, drop it and pin a commit: `git+https://github.com/Marvin-Labs/marvin-mcp@<sha>`.

## Tools

| Tool | Does |
|---|---|
| `ask_marvin(question, conversation_id?)` | Asks a question, in a new conversation or continuing one. Returns the answer, or a `response_id` if it is still working |
| `get_response(response_id)` | Waits a little longer for an answer that is still running |
| `cancel_response(response_id)` | Stops a running answer |
| `list_conversations(limit?, cursor?)` | Your conversations, most recent first, including the app's |
| `get_conversation(conversation_id, limit?, cursor?)` | A conversation's questions and answers |
| `list_agent_results(company?, agent?, mine?, limit?, cursor?)` | Reports Marvin's research agents have written that you can read: yours, shared with you, and public ones |
| `get_agent_result(agent_result_id)` | One report, in full |
| `get_format_guide()` | How to show the table and chart blocks in answers |

Answers often take a few minutes. MCP clients give up on a tool call long before that, so `ask_marvin` starts the answer in the background and waits for at most `MARVIN_WAIT_SECONDS` (default 50). If the answer isn't ready by then, the model calls `get_response` until it is.

Answers can contain tables and charts, written as JSON in ```` ```financial-table ```` and ```` ```echarts ```` blocks that the Marvin app renders. `get_format_guide` explains how to turn the blocks into markdown tables, or into charts if the client can draw them.

## Configuration

| Variable | Default | |
|---|---|---|
| `MARVIN_API_KEY` | (required) | Your Marvin API key |
| `MARVIN_API_URL` | `https://app-api.marvin-labs.com` | Another environment, e.g. stg or a local API (`http://localhost:<port>`) |
| `MARVIN_WAIT_SECONDS` | `50` | How long one tool call waits for an answer |

Every answer is a normal Marvin chat turn and uses your credits the same way.

## Development

```bash
uv run pytest
MARVIN_API_KEY=ak_... MARVIN_API_URL=http://localhost:<port> uv run marvin-mcp   # stdio
```

To try a change in real clients before it is published, run setup from your checkout and pass `--source`, so the clients also start the server from it (add `--api-url` for stg or a local API):

```bash
uvx --from <checkout> marvin-mcp setup --source <checkout>
```

uv rebuilds the checkout whenever a file under `src/` changes (`[tool.uv] cache-keys` in `pyproject.toml`), so the next run and the next client restart pick up your edits. Run setup again without `--source` to switch back to the published version.

This repository is published automatically from Marvin Labs' main codebase, where the client is maintained, and is replaced on every release. Changes made here are overwritten, so it does not take pull requests.

## Licence

MIT, see [LICENSE](LICENSE).