Metadata-Version: 2.4
Name: obris-mcp
Version: 0.3.0
Summary: MCP server for Obris - bring your curated knowledge into any AI conversation
Project-URL: Homepage, https://obris.ai
Project-URL: Repository, https://github.com/obris-dev/obris-mcp
Project-URL: Documentation, https://docs.obris.ai
Author-email: Obris <dev@obris.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chatgpt,claude,context,knowledge-management,llm,mcp,mcp-server,model-context-protocol,obris,rag,second-brain,web-clipper
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Obris MCP Server

<!-- mcp-name: ai.obris/mcp -->

An [MCP](https://modelcontextprotocol.io/) server that brings your curated [Obris](https://obris.ai) knowledge into any AI conversation. Use the [Chrome extension](https://chromewebstore.google.com/detail/obris-%E2%80%93-save-key-content/kkkiblfabiopcmoghfcjffiobjlppfdp) or upload directly to save knowledge to dedicated topics so you never start another AI chat from zero again.

## Features

- **List topics** — Browse all your Obris topics to find the one you need
- **Pull in knowledge** — Retrieve saved bookmarks, highlights, and notes as context for any conversation
- **Save knowledge** — Capture takeaways and notes from conversations to reuse in future chats

## Setup

### 1. Get your API key

Generate an API key from your [Obris dashboard](https://app.obris.ai/api-keys). Don't have an account? [Sign up](https://app.obris.ai/signup).

### 2. Install and configure

#### Claude Desktop

Add your API key to your shell profile (`~/.zshrc`, `~/.zprofile`, or `~/.bash_profile`):

```bash
export OBRIS_API_KEY=your_api_key_here
```

Then reload your shell:

```bash
source ~/.zshrc
```

Open Claude Desktop settings → **Developer** → **Edit Config**, and add the following to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obris": {
      "command": "/full/path/to/uvx",
      "args": ["obris-mcp"],
      "env": {
        "OBRIS_API_KEY": "$OBRIS_API_KEY"
      }
    }
  }
}
```

> Run `which uvx` to get the full path for `"command"`.

Restart Claude Desktop to pick up the changes.

#### Claude Code

```bash
claude mcp add Obris -e OBRIS_API_KEY=$OBRIS_API_KEY --transport stdio -- uvx obris-mcp
```

Start a new conversation and type `/mcp` to verify the Obris server is connected.

#### Gemini CLI

```bash
gemini mcp add -e OBRIS_API_KEY=$OBRIS_API_KEY --transport stdio Obris uvx obris-mcp
```

Start a new Gemini session and run `/mcp` to verify the Obris server is connected.

#### Other MCP clients

See the [local MCP setup guide](https://docs.obris.ai/guides/local-mcp) for more options.

## Tools

| Tool | Description |
|------|-------------|
| `list_topics` | List all your Obris topics |
| `get_topic_knowledge` | Get saved knowledge for a specific topic |
| `create_topic` | Create a new topic to organize knowledge |
| `add_knowledge` | Save text knowledge to a topic |

## Examples

### Example 1: Listing your topics

**Prompt:** "What Obris topics do I have?"

The `list_topics` tool is called and returns:

```
Topics:
- Brand Guidelines (id: 01JEXAMPLE00001)
- Marketing Images (id: 01JEXAMPLE00002)
- Shoe Dog Highlights (id: 01JEXAMPLE00003)
- Favorite Cocktails (id: 01JEXAMPLE00004)
```

### Example 2: Getting knowledge for a topic

**Prompt:** "What are repeated lessons in my Shoe Dog highlights? Cite the original highlight in your answer."

The `list_topics` tool finds the topic, then `get_topic_knowledge` retrieves your saved highlights:

```
### On Starting Out
"I'd tell men and women in their midtwenties not to settle
for a job or a profession or even a career. Seek a calling."
---
### On Selling
"Don't tell people about your brand. Tell them about your
belief. The ones who share it will find you."
```

### Example 3: Using knowledge to make a decision

**Prompt:** "Here's a cocktail menu. Based on my saved favorites, what should I order?"

The `list_topics` tool finds Favorite Cocktails, then `get_topic_knowledge` retrieves your saved recipes and tasting notes. The AI cross-references the menu with your preferences to recommend a drink you'll actually like.

### Example 4: Combining multiple topics

**Prompt:** "Pull in my brand guidelines and marketing images. Help me design a new hero section with more of an Apple-style design approach."

The AI retrieves knowledge from both topics — your color palette, typography rules, tone of voice, and previous marketing visuals — then uses that context to generate a hero section concept that stays on-brand while incorporating the clean, minimal aesthetic you're going for.

## Development

```bash
git clone https://github.com/obris-dev/obris-mcp.git
cd obris-mcp
uv sync
```

To run locally via Claude Desktop, add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obris": {
      "command": "/full/path/to/uv",
      "args": [
        "--directory",
        "/path/to/obris-mcp/src/obris_mcp",
        "run",
        "main.py"
      ],
      "env": {
        "OBRIS_API_KEY": "$OBRIS_API_KEY"
      }
    }
  }
}
```

> Run `which uv` to get the full path for `"command"`.

### Make commands

```bash
make publish            # build and publish to PyPI
make pack               # pack for MCP registry (runs version check first)
make pack-and-publish   # pack, publish to PyPI, and publish to MCP registries
make sync-version       # sync manifest.json and server.json to pyproject.toml version
make check-version      # verify all version files match and compare to live server
```

## Privacy Policy

This server sends your Obris API key to the Obris API (`api.obris.ai`) to authenticate requests. It retrieves topic and knowledge data from your account. The server itself does not store any data locally or send it to any third party, however your AI client may cache or retain retrieved content according to its own data policies.

For the full privacy policy, see [obris.ai/privacy](https://obris.ai/privacy).

## Support

For issues or questions, contact [support@obris.ai](mailto:support@obris.ai) or open an issue on [GitHub](https://github.com/obris-dev/obris-mcp/issues).

## License

MIT
