Claude Code

Claude Code is Anthropic's coding agent for the terminal and code editors. Connected to your Omeka site, it can search and read the collection, create and edit items, and upload files from your computer, all as your Omeka user.

Before you start#

• Install Claude Code and sign in to it.
• Find your site's MCP address. It is shown on Admin > MCP connections, and is your site's address followed by /mcp, for example https://archive.example.org/mcp.
• Decide how Claude Code will sign in. Your Omeka account (OAuth) is the simplest. Use an API key on machines without a browser, or if an administrator has turned off signing in.

Connect with your Omeka account#

1. In a terminal, add the server:

   claude mcp add --transport http omeka https://archive.example.org/mcp
   

2. Start Claude Code, type /mcp, choose omeka, then Authenticate. You can also run claude mcp login omeka from the terminal.

3. Your browser opens your Omeka site. Sign in if asked, review the permissions, and choose Allow. Untick Create and edit to give Claude Code read-only access.

4. Back in Claude Code, ask: "Using the omeka tools, what is in this collection?" Claude calls omeka_info and describes the site.

Claude Code stores the sign-in and renews it by itself. On a remote machine without a browser, run claude mcp login omeka --no-browser: it prints the sign-in address to open on another device, then asks you to paste back the address your browser ends up on.

Connect with an API key#

1. In the Omeka admin, open your user page (Admin > Users > your name > Edit) and go to the API keys tab.

2. Create a key. Copy the key identity and the credential: the credential is shown only once.

3. Add the server, joining the identity and credential with a colon:

   claude mcp add --transport http omeka https://archive.example.org/mcp --header "Authorization: Bearer KEY_IDENTITY:KEY_CREDENTIAL"
   

API keys do not expire. To cut off access, delete the key on your user page.

Choose where the server is available#

claude mcp add takes a --scope option:

Share the setup with a team#

A project-scoped server lives in .mcp.json at the root of the project, which you can commit. With sign-in, the file holds no secrets; each person authenticates with their own Omeka account the first time:

{
  "mcpServers": {
    "omeka": {
      "type": "http",
      "url": "https://archive.example.org/mcp"
    }
  }
}

To use API keys instead, keep each person's key out of the file with an environment variable:

{
  "mcpServers": {
    "omeka": {
      "type": "http",
      "url": "https://archive.example.org/mcp",
      "headers": {
        "Authorization": "Bearer ${OMEKA_MCP_TOKEN}"
      }
    }
  }
}

Each person then sets OMEKA_MCP_TOKEN to their own KEY_IDENTITY:KEY_CREDENTIAL before starting Claude Code.

Approve tool calls#

Claude Code asks before it runs a tool for the first time. Tools that only read are marked as read-only, and tools that change the collection are marked as writes, so you can decide what to pre-approve. For example, to let Claude Code search and read without asking, add the read tools to the permissions.allow list in .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__omeka__omeka_info",
      "mcp__omeka__search_vocabulary",
      "mcp__omeka__get_resource_template",
      "mcp__omeka__search_resources",
      "mcp__omeka__get_resource"
    ]
  }
}

Keep the editing tools on ask until you trust the workflow. Uploading files also runs curl, which Claude Code asks about separately; add Bash(curl:*) to the list to allow it.

Large results and slow downloads#

• Claude Code limits a tool result to 25,000 tokens. Searches return pages of at most 50 summaries and long text values are shortened, so this is rarely reached. If it is, ask for smaller pages, or start Claude Code with a higher limit: MAX_MCP_OUTPUT_TOKENS=50000 claude.
• Adding media from a web address makes the server download the file while the tool runs. For very large files, upload them from your computer instead (see Working with an agent).

Disconnect#

• Signed in with your account: choose Disconnect next to Claude Code on Admin > MCP connections. To forget the sign-in on your computer, run claude mcp logout omeka.
• Using an API key: delete the key on your user page.
• To remove the server from Claude Code: claude mcp remove omeka.