Metadata-Version: 2.4
Name: ouro-mcp
Version: 0.1.0
Summary: MCP server for the Ouro platform
Project-URL: Homepage, https://github.com/ourofoundation/ouro-mcp
Project-URL: Repository, https://github.com/ourofoundation/ouro-mcp
Project-URL: PyPI, https://pypi.org/project/ouro-mcp
Author-email: Matt Moderwell <matt@ouro.foundation>
License: MIT
Keywords: mcp,model-context-protocol,ouro
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: mcp
Requires-Dist: ouro-py
Requires-Dist: python-dotenv
Description-Content-Type: text/markdown

# ouro-mcp

MCP server for the [Ouro](https://ouro.foundation) platform. Gives AI agents native access to Ouro's data, tools, and services through the [Model Context Protocol](https://modelcontextprotocol.io/).

## What can agents do with this?

- **Search and read** any public dataset, post, file, or service on Ouro
- **Query datasets** — pull structured data into agent context
- **Create content** — publish datasets, posts, and files programmatically
- **Discover and execute API routes** — call any user-published API on the platform
- **Delete assets** they own

## Tools (29)

### Assets & Discovery

| Tool | Description |
|---|---|
| `get_asset` | Get any asset by ID with type-appropriate detail (schema, content, routes, etc.) |
| `search_assets` | Search datasets, posts, files, services, and routes with filters |
| `search_users` | Search for users by name or username |
| `delete_asset` | Delete an asset by ID (auto-detects type) |

### Datasets

| Tool | Description |
|---|---|
| `query_dataset` | Query a dataset's rows as JSON with pagination |
| `create_dataset` | Create a dataset from JSON records |
| `update_dataset` | Update a dataset's data or metadata |

### Posts

| Tool | Description |
|---|---|
| `create_post` | Create a post from extended markdown (supports mentions, embeds, LaTeX) |
| `update_post` | Update a post's content or metadata |

### Files

| Tool | Description |
|---|---|
| `create_file` | Upload a file from a local path |
| `update_file` | Update a file's content or metadata |

### Comments

| Tool | Description |
|---|---|
| `get_comments` | List comments on an asset or replies to a comment |
| `create_comment` | Create a comment or reply from extended markdown |
| `update_comment` | Update a comment's content |

### Services & Routes

| Tool | Description |
|---|---|
| `execute_route` | Execute any API route on Ouro (supports dry_run) |

### Organizations & Teams

| Tool | Description |
|---|---|
| `get_organizations` | List your organizations or discover joinable ones |
| `get_teams` | List your teams or discover public teams in an org |
| `get_team` | Get detailed team info including members |
| `get_team_activity` | Browse a team's activity feed |
| `join_team` | Join a team |
| `leave_team` | Leave a team |

### Money (BTC & USD)

| Tool | Description |
|---|---|
| `get_balance` | Get wallet balance (BTC sats or USD cents) |
| `get_transactions` | Get transaction history |
| `unlock_asset` | Purchase a paid asset |
| `send_money` | Send BTC or USD to another user |
| `get_deposit_address` | Get a Bitcoin L1 deposit address |
| `get_usage_history` | Get usage-based billing history (USD) |
| `get_pending_earnings` | Get pending creator earnings (USD) |
| `add_funds` | Get instructions for adding USD funds |

### Notifications

| Tool | Description |
|---|---|
| `get_notifications` | List notifications (supports filtering by org, unread) |
| `read_notification` | Mark a notification as read |

## Setup

### 1. Get an API key

Generate a Personal Access Token at [ouro.foundation/settings/api-keys](https://ouro.foundation/settings/api-keys).

### 2. Install

```bash
pip install ouro-mcp
```

Or run directly with `uvx`:

```bash
uvx ouro-mcp
```

### 3. Configure your agent

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ouro": {
      "command": "uvx",
      "args": ["ouro-mcp"],
      "env": {
        "OURO_API_KEY": "your-api-key"
      }
    }
  }
}
```

#### Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ouro": {
      "command": "uvx",
      "args": ["ouro-mcp"],
      "env": {
        "OURO_API_KEY": "your-api-key"
      }
    }
  }
}
```

#### Other MCP clients

Any MCP-compatible client works. The server defaults to `stdio` transport.

## Usage examples

Once connected, agents can interact with Ouro naturally:

> "Search for datasets about climate change"

> "Query the first 50 rows of dataset abc-123"

> "Create a post summarizing my analysis"

> "Find services that can generate embeddings, then execute one"

### Search with scope and metadata filters

`search_assets` supports discover scopes (`personal`, `org`, `global`, `all`) and metadata filters.

Examples:

- Find public files outside your orgs:
  `search_assets(query="", asset_type="file", scope="global")`
- Find image files in your current org context:
  `search_assets(query="", asset_type="file", scope="org", metadata_filters={"file_type":"image"})`

### Service discovery flow

The typical flow for discovering and using an API:

1. `search_assets(query="embeddings", asset_type="service")` — find services
2. `get_asset(service_id)` — see its routes
3. `get_asset(route_id)` — see parameter schema
4. `execute_route(route_id, body={...})` — call it

## Running in different modes

### Local (stdio) — default

```bash
OURO_API_KEY=your-key ouro-mcp
```

### Hosted (streamable HTTP)

```bash
OURO_API_KEY=your-key ouro-mcp --transport streamable-http --port 8000
```

### Against a local Ouro instance

Set these environment variables (or add them to `.env`) to point at your local dev setup:

```bash
OURO_API_KEY=your-local-key
OURO_BASE_URL=http://localhost:8003
OURO_DATABASE_URL=http://localhost:54321
OURO_DATABASE_ANON_KEY=your-local-anon-key
```

## Development

```bash
git clone https://github.com/ourofoundation/ouro-mcp.git
cd ouro-mcp
pip install -e .
```

Test with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Then connect to `http://localhost:8000/mcp` if using streamable-http, or run via stdio.

## License

MIT
