# project-hub-mcp

> Run AI agent pipelines from Devin, Claude, and Cursor — via MCP.

**Project Hub MCP** is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets your AI tools run multi-step agent pipelines directly from a conversation.

Built on top of [Project Hub](https://github.com/atikahjapry/project-hub) — the open-source AI agent pipeline desktop app.

---

## What it does

Once installed, your AI assistant can:

- **`list_pipelines`** — see all your pipelines
- **`run_pipeline`** — execute a pipeline (Issue Analyst → Code Writer → Test Runner → PR Opener)
- **`get_run_status`** — check logs and output of a run
- **`list_agents`** — see all available agents (Devin, shell, Python, HTTP)
- **`run_agent`** — run a single agent step with any input
- **`create_pipeline`** — define a new pipeline on the fly
- **`get_usage`** — check your monthly run count

---

## Install

### Devin

Add to your Devin MCP settings:

```json
{
  "mcpServers": {
    "project-hub": {
      "command": "npx",
      "args": ["-y", "project-hub-mcp"],
      "env": {
        "PROJECT_HUB_API_KEY": "phub_your_key_here"
      }
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "project-hub": {
      "command": "npx",
      "args": ["-y", "project-hub-mcp"],
      "env": {
        "PROJECT_HUB_API_KEY": "phub_your_key_here"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "project-hub": {
      "command": "npx",
      "args": ["-y", "project-hub-mcp"],
      "env": {
        "PROJECT_HUB_API_KEY": "phub_your_key_here"
      }
    }
  }
}
```

### Local mode (no key required)

Set `PROJECT_HUB_LOCAL_MODE=1` to run locally with no API key and no run limits:

```json
{
  "mcpServers": {
    "project-hub": {
      "command": "npx",
      "args": ["-y", "project-hub-mcp"],
      "env": {
        "PROJECT_HUB_LOCAL_MODE": "1"
      }
    }
  }
}
```

---

## Usage examples

Once installed, just talk to your AI:

> *"List my Project Hub pipelines"*

> *"Run the GitHub Issue → PR pipeline with input: Fix the login bug described in issue #42"*

> *"Check the status of run abc-123"*

> *"Run the Code Writer agent on this task: Add dark mode to the settings page"*

---

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `PROJECT_HUB_API_KEY` | — | Your API key (get one free at https://projecthub.dev/api-key) |
| `PROJECT_HUB_LOCAL_MODE` | `0` | Set to `1` for unlimited local runs, no key needed |
| `PROJECT_HUB_DATA` | `~/.project-hub-mcp` | Directory where agents, pipelines, and run history are stored |
| `DEVIN_MODEL` | — | Default Devin model (e.g. `claude-sonnet-4`) |
| `DEVIN_PERMISSION_MODE` | `auto` | Devin permission mode: `auto`, `smart`, or `dangerous` |
| `DEVIN_WORKING_DIR` | `$HOME` | Default working directory for Devin agent runs |

---

## Pricing

| Plan | Price | Runs/month |
|---|---|---|
| Free | £0 | 10 |
| Pro | £19/mo | Unlimited |

Get your free API key: **https://projecthub.dev/api-key**

---

## Run from source

```bash
git clone https://github.com/atikahjapry/project-hub-mcp
cd project-hub-mcp
npm install
npm run build

# Run in local mode (no key, no limits)
PROJECT_HUB_LOCAL_MODE=1 node dist/index.js
```

---

## Security

### Data stored locally

Agents, pipelines, and run history are stored in `~/.project-hub-mcp/store.json` on your own machine. The directory is created with mode `0700` and the file with mode `0600` — readable only by your user account.

API keys are hashed with SHA-256 before being stored. The raw key is never written to disk.

### Secrets in `envVars`

When creating a shell or Python agent, the `envVars` field sets environment variables for the spawned process. **Use `$VARIABLE_NAME` references, not literal values** — the reference is stored, and the real value is resolved from your shell environment at runtime and never written to disk.

```jsonc
// Bad — literal token stored in store.json in plaintext
{ "GITHUB_TOKEN": "ghp_actualtoken123" }

// Good — reference stored; real value read from host env at runtime
{ "GITHUB_TOKEN": "$GITHUB_TOKEN" }
```

The server **enforces** this: `saveAgent` will throw if it detects a known secret pattern (GitHub tokens, OpenAI keys, AWS keys, long hex strings, etc.) in an `envVars` value. If you try to save such an agent you will get a clear error pointing to the offending key and showing the correct `$REF` form.

Put real secrets in your shell profile (`~/.bashrc`, `~/.zshrc`) or your MCP host's `env` config block, then reference them by name.

### Shell commands

Shell and Python agents run `bash -c <your-command>`. The user input passed to the agent is **not** interpolated into the command string — it is passed via the `AGENT_INPUT` environment variable to prevent shell injection.

Reference it in your command like this:

```bash
# Access user input safely via $AGENT_INPUT
echo "$AGENT_INPUT" | some-tool
```

### Logs

All stdout/stderr captured during agent runs is scrubbed for common secret patterns (`token=`, `password=`, `Bearer`, etc.) before being stored. If you need to ensure sensitive output is never logged, set `outputParser: "last_line"` or `"json_field"` on the agent to capture only structured output.

---

## How it works

- Agents and pipelines are stored locally in `~/.project-hub-mcp/store.json`
- The server runs via stdio — your AI tool spawns it as a subprocess
- Devin agents call the `devin` CLI — you need Devin installed (`https://devin.ai/download`)
- Shell agents run via `bash -c`; user input passed via `AGENT_INPUT` env var (never interpolated into the command)
- All run logs and outputs are persisted locally with secret scrubbing applied

---

## Related

- [Project Hub desktop app](https://github.com/atikahjapry/project-hub) — the full GUI for building and running pipelines
- [Project Hub landing page](https://github.com/atikahjapry/project-hub-landing) — marketing site and agent marketplace

---

MIT License · Built by [Atikah Japry](https://github.com/atikahjapry)