reflect-mcp by adstastic - MCP Server

Reflect MCP Server

A Python MCP (Model Context Protocol) server that provides seamless integration with the Reflect Notes API. This server enables AI assistants to interact with your Reflect notes, allowing you to create notes, save links, append to daily notes, and manage your knowledge graph programmatically.

Features

OAuth2 Authentication: Secure authentication flow with automatic token management
Note Management: Create new notes with Markdown content
Daily Notes: Append text to daily notes with optional list targeting
Link Saving: Save web links with titles, descriptions, and highlights
Graph Operations: List and manage multiple knowledge graphs
User Management: Get current user information and default graph settings

Installation

Quick Start with uvx (Recommended)

No need to clone the repository! Simply configure and run:

{
  "mcpServers": {
    "reflect": {
      "command": "uvx",
      "args": ["reflect-mcp"],
      "env": {
        "REFLECT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

To get your access token:

Go to Reflect Developer OAuth
Create credentials if you haven't already
Generate an access token
Copy the token and add it to the configuration above

Manual Installation

pip install reflect-mcp

Or with uv:

uv pip install reflect-mcp

Configuration

Using an Access Token (Recommended)

The simplest way to use the server is with a direct access token:

REFLECT_ACCESS_TOKEN=your_access_token_here
REFLECT_DEFAULT_GRAPH_ID=your_default_graph_id  # Optional

To get your access token:

Go to Reflect Developer OAuth
Create credentials if you haven't already
Generate an access token
Copy the token and add it to your configuration

Using OAuth2 (Alternative)

If you prefer OAuth2 authentication:

REFLECT_CLIENT_ID=your_oauth_client_id
REFLECT_CLIENT_SECRET=your_oauth_client_secret
REFLECT_REDIRECT_URI=http://localhost:8080/callback  # Optional
REFLECT_DEFAULT_GRAPH_ID=your_default_graph_id  # Optional

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using the published package with access token:

{
  "mcpServers": {
    "reflect": {
      "command": "uvx",
      "args": ["reflect-mcp"],
      "env": {
        "REFLECT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

If running from source:

{
  "mcpServers": {
    "reflect": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/reflect-mcp",
        "run",
        "reflect_server.py"
      ],
      "env": {
        "REFLECT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Alternative OAuth2 configuration (if not using access token):

{
  "mcpServers": {
    "reflect": {
      "command": "uvx",
      "args": ["reflect-mcp"],
      "env": {
        "REFLECT_CLIENT_ID": "your_client_id",
        "REFLECT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Available Tools

Authentication

authenticate - Start OAuth2 authentication flow (opens browser)
set_access_token - Complete OAuth2 flow with authorization code
set_token_directly - Set access token manually (useful if you already have one)

Graphs

list_graphs - Get all accessible graphs with IDs, names, and timestamps
get_default_graph - Get the default graph ID from configuration or user profile

Notes & Content

create_note - Create a new note with title and Markdown content
append_daily_note - Append text to daily note (today or specific date)
list_books - Get all books in a graph
list_links - Get all links in a graph
create_link - Save a web link with optional metadata

User

get_current_user - Get information about the authenticated user

Authentication

Using Access Token (Recommended)

If you've configured the server with REFLECT_ACCESS_TOKEN, you're already authenticated and can start using all tools immediately.

Using OAuth2 Flow

If you're using OAuth2 credentials instead of a direct access token:

Start the authentication process:
```
authenticate
```
This opens your browser to the Reflect OAuth page.
After authorizing, you'll be redirected to a URL containing an authorization code.

Complete authentication by providing the code:

set_access_token code="your_authorization_code"

The server will handle token exchange and refresh automatically.

Usage Examples

Create a Note

create_note(
    subject="Meeting Notes",
    content="## Project Review\n\n- Discussed timeline\n- Set Q2 goals",
    pinned=false
)

Append to Daily Note

# Append to today's daily note
append_daily_note(
    text="Remember to review the project proposal"
)

# Append to a specific list in yesterday's note
append_daily_note(
    text="Completed user authentication feature",
    date="2024-01-18",
    list_name="Done"
)

Save a Link

create_link(
    url="https://example.com/article",
    title="Interesting Article",
    description="Key insights about productivity",
    highlights=["Important quote from the article", "Another highlight"]
)

List and Manage Graphs

# Get all accessible graphs
list_graphs()

# Get the default graph ID
get_default_graph()

# List all links in a specific graph
list_links(graph_id="your_graph_id")

Resources

The server provides these MCP resources for checking status:

get_auth_status (reflect://auth/status): Check current authentication status
get_config (reflect://config): View current configuration (excluding secrets)

Prompts

Built-in workflow prompts for common tasks:

create_reading_list: Template for creating organized reading lists in Reflect
daily_journal_workflow: Structured template for daily journaling

Development

Running from Source

# Clone the repository
git clone https://github.com/yourusername/reflect-mcp
cd reflect-mcp

# Install dependencies
uv sync

# Run in development mode
uv run mcp dev reflect_mcp/server.py

Testing

# Run with MCP inspector for testing
uv run mcp inspector reflect_mcp/server.py

Building and Publishing

# Build the package
uv build

# Publish to PyPI (requires credentials)
uv publish

API Reference

The server implements the Reflect API v0.1.0 with the following endpoints:

GET /graphs - List all graphs
GET /graphs/{id}/books - List books in a graph
GET /graphs/{id}/links - List links in a graph
POST /graphs/{id}/links - Create a new link
POST /graphs/{id}/notes - Create a new note
PUT /graphs/{id}/daily-notes - Append to daily note
GET /users/me - Get current user info

Authentication

The Reflect API uses OAuth2 with the following flows:

Authorization URL: https://reflect.app/oauth
Token URL: https://reflect.app/api/oauth/token
Scopes:
- read:graph - Read access to protected resources
- write:graph - Write access to protected resources

Troubleshooting

Authentication Issues

Missing credentials: Ensure REFLECT_CLIENT_ID and REFLECT_CLIENT_SECRET are set
Invalid redirect: Check that your OAuth app's redirect URI matches the server's expected callback
Token refresh: The server automatically handles token refresh using the authlib library

Connection Errors

Verify your internet connection
Check if the Reflect API is accessible at https://api.reflect.app
Review server logs for detailed error messages
Ensure your OAuth app has the necessary scopes enabled

Common Issues

"Server disconnected" error in Claude: Usually means the server couldn't start. Check:
- OAuth credentials are correctly set
- No syntax errors in configuration
- The reflect_server.py file exists (if running from source)
"Not authenticated" errors: Run the authenticate tool first to set up OAuth
Graph ID errors: Use list_graphs to find valid graph IDs, or set REFLECT_DEFAULT_GRAPH_ID

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please use the GitHub issue tracker.